@pega/sdk 0.0.14 → 0.0.15

package/templates/react-sdk-reference/.ai-common/prompts/add-component.md

@@ -2,6 +2,16 @@
 ai-description: Add a new component type to the registry
 ---
 
+## Progress milestones
+
+Announce these to the user as you reach them, in plain words and with a counter — "Step 3 of 4 — Building the component". Count only the milestones that apply to this run.
+
+1. **Understanding your request** — Step 0
+2. **Preparing your design system** — Steps 1 to 3
+3. **Building the component** — Steps 5 and 6
+4. **Checking the app builds** — Step 7
+5. **Trying it out** — Step 8
+
 ## Step 0 — Resolve missing information
 
 Read the user's message carefully. Extract:
@@ -13,19 +23,23 @@ Read the user's message carefully. Extract:
 
 All four values above are required. If any are missing or ambiguous, you MUST stop and ask the user before proceeding. Do not infer any value from the project structure, `{{AI_FILE_EXT}}` files, existing folders, or any other source.
 
+**One exception — component type.** Once the component name is resolved to a canonical name, take its type from `{{PROMPT_DIR}}/component-manifest.json` and ask the user to confirm it in plain words, in the same message as any other missing items — for example "I'll treat the date picker as a form field — is that right?". Ask the user for the type only when the name cannot be resolved. Every other value still comes from the user.
+
 ⛔ **STOP** — If the user's message does not explicitly provide ALL of: component name, component type, design system, and output path — ask for the missing items now. Do not proceed to Step 1 until you have explicit answers from the user for all required inputs.
 
-Example questions to ask (only ask the ones that are actually missing):
+Ask every missing item together, in one plain message. Example questions to ask (only ask the ones that are actually missing):
 
-1. Which design system should I use? (e.g. Ant Design, Chakra UI, Carbon, Radix UI)
-2. What is the exact component name?
-3. What type of component is this? (field / template / widget / designSystemExtension / infra)
+1. Which style kit should I use for the screens? (A style kit is a ready-made set of buttons, inputs, and layouts.) Before asking, check the project's dependency list for UI libraries and list any you find first, marked as already in the project, then offer Ant Design, Chakra UI, Carbon, Radix UI, or another. Never choose one on the user's behalf, even when only one is installed.
+2. Which piece of the screen should I build? (Describe it in your own words if you don't know its name.)
+3. What kind of piece is this — a form field, a page layout, a panel, a display piece, or one of the buttons or progress indicators? (Only when the name could not be resolved; otherwise confirm the type as described above.)
 4. What is the exact or relative path where the component should be generated? (e.g. `src/components/field/AutoComplete`)
 
 ### Case-insensitive component name matching
 
 The user may enter the component name in any casing (e.g. `autocomplete`, `Autocomplete`, `autoComplete`). It is your responsibility to match it to the correct canonical name by checking the skill files in `{{SKILL_DIR}}/field-skills/`, `{{SKILL_DIR}}/template-skills/`, `{{SKILL_DIR}}/widget-skills/`, `{{SKILL_DIR}}/design-system-extension-skills/`, and `{{SKILL_DIR}}/infra-skills/`. For example, if the user types `autocomplete`, match it to `AutoComplete`.
 
+The user may also describe the component in everyday words ("date picker", "the buttons at the bottom"). Resolve those through the `aliases` and `behaviorClasses` in `{{PROMPT_DIR}}/component-manifest.json`, and confirm the match with the user before continuing. If nothing matches, ask the user which piece they mean — never guess.
+
 Once all four are known, continue to Step 1.
 
 ---
@@ -36,6 +50,7 @@ Before generating, check if a component already exists at the resolved output pa
 
 1. Check if the component file or directory already exists at the resolved output path.
 2. If it **does exist**, ask the user: _"A component named `<ComponentName>` already exists at `<outputPath>`. Do you want to overwrite it with the new implementation?"_
+   - Ask it in plain words, naming the piece exactly as the user did — for example _"You already have a date picker. Replace it with the new one, or keep yours?"_. If they called it "combo box", say "combo box"; never swap in a synonym or the component name. If the user did not name it, use `<ComponentName> – plain description` (the first summary line of its skill file, reworded into a few plain words). "Replace" means **yes**, "keep" means **no**.
    - If the user says **yes**, proceed to overwrite.
    - If the user says **no**, stop and skip generation.
 3. If it **does not exist**, continue to Step 2.
@@ -46,25 +61,25 @@ Before generating, check if a component already exists at the resolved output pa
 
 Always read the **general type skill** for the component type:
 
-| Component Type          | General Skill File                         |
-| ----------------------- | ------------------------------------------ |
-| `field`                 | `{{SKILL_DIR}}/field-components.md`        |
-| `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`        |
+| Component Type          | General Skill File                                   |
+| ----------------------- | ---------------------------------------------------- |
+| `field`                 | `{{SKILL_DIR}}/field-components{{SKILL_EXT}}`        |
+| `template`              | `{{SKILL_DIR}}/template-components{{SKILL_EXT}}`     |
+| `widget`                | `{{SKILL_DIR}}/widget-components{{SKILL_EXT}}`       |
+| `designSystemExtension` | `{{SKILL_DIR}}/design-system-extension{{SKILL_EXT}}` |
+| `infra`                 | `{{SKILL_DIR}}/infra-components{{SKILL_EXT}}`        |
 
 Only three `infra` components may be added — `ActionButtons`, `Stages`, and `MultiStep`. Every other infrastructure component is SDK-provided; if the user names one, stop and tell them it is not generated.
 
 Then look for a **component-specific skill** based on the component type:
 
-| Component Type          | Specific Skill Location                                           |
-| ----------------------- | ----------------------------------------------------------------- |
-| `field`                 | `{{SKILL_DIR}}/field-skills/<ComponentName>.md`                   |
-| `template`              | `{{SKILL_DIR}}/template-skills/<ComponentName>.md`                |
-| `widget`                | `{{SKILL_DIR}}/widget-skills/<ComponentName>.md`                  |
-| `designSystemExtension` | `{{SKILL_DIR}}/design-system-extension-skills/<ComponentName>.md` |
-| `infra`                 | `{{SKILL_DIR}}/infra-skills/<ComponentName>.md`                   |
+| Component Type          | Specific Skill Location                                                     |
+| ----------------------- | --------------------------------------------------------------------------- |
+| `field`                 | `{{SKILL_DIR}}/field-skills/<ComponentName>{{SKILL_EXT}}`                   |
+| `template`              | `{{SKILL_DIR}}/template-skills/<ComponentName>{{SKILL_EXT}}`                |
+| `widget`                | `{{SKILL_DIR}}/widget-skills/<ComponentName>{{SKILL_EXT}}`                  |
+| `designSystemExtension` | `{{SKILL_DIR}}/design-system-extension-skills/<ComponentName>{{SKILL_EXT}}` |
+| `infra`                 | `{{SKILL_DIR}}/infra-skills/<ComponentName>{{SKILL_EXT}}`                   |
 
 If the component-specific skill file exists, read it fully. Pay special attention to:
 
@@ -157,7 +172,7 @@ If a component-specific skill file exists, follow its Behavioral Contract for da
 
 ### designSystemExtension
 
-Follow the implementation structure described in `design-system-extension.md` (read in Step 2). That file specifies the pattern variants (pure display, PConnect display, complex display) for this project's framework.
+Follow the implementation structure described in `design-system-extension.md` (read in Step 2). That file specifies the pattern variants (pure display, data display, complex display) for this project's framework.
 
 ---
 
@@ -191,3 +206,9 @@ Do not restructure or reorder any existing entries.
 Run the project's build process to confirm everything compiles without errors.
 
 If build errors occur, diagnose and fix them before reporting completion. Report what files were created and what was registered in the component map.
+
+---
+
+## Step 8 — Try the portal
+
+Once the Step 7 build passes, read and execute `{{SKILL_DIR}}/portal-flow/run-and-verify-portal{{SKILL_EXT}}`, handing it the component you added. Report its verification summary together with the Step 7 report.

package/templates/react-sdk-reference/.ai-common/prompts/component-manifest.json

@@ -18,6 +18,24 @@
       ]
     }
   },
+  "scopeAliases": {
+    "form fields": "field",
+    "fields": "field",
+    "inputs": "field",
+    "page layouts": "template",
+    "layouts": "template",
+    "templates": "template",
+    "panels": "widget",
+    "widgets": "widget",
+    "display pieces": "designSystemExtension",
+    "banners and messages": "designSystemExtension",
+    "buttons and progress bars": "infra",
+    "forms": "workflow-form",
+    "the forms": "workflow-form",
+    "the whole app": "all",
+    "everything": "all",
+    "all components": "all"
+  },
   "components": {
     "field": [
       { "name": "AutoComplete", "path": "src/components/field/AutoComplete" },
@@ -163,6 +181,10 @@
         "name": "AlertBanner",
         "path": "src/components/designSystemExtension/AlertBanner"
       },
+      {
+        "name": "AssignmentHeader",
+        "path": "src/components/designSystemExtension/AssignmentHeader"
+      },
       {
         "name": "Banner",
         "path": "src/components/designSystemExtension/Banner"
@@ -196,6 +218,7 @@
         "name": "RichTextEditor",
         "path": "src/components/designSystemExtension/RichTextEditor"
       },
+      { "name": "Toast", "path": "src/components/designSystemExtension/Toast" },
       {
         "name": "WssQuickCreate",
         "path": "src/components/designSystemExtension/WssQuickCreate"
@@ -257,7 +280,35 @@
     "Assignee": "UserReference",
     "Label": "TextContent",
     "StaticText": "TextContent",
-    "Paragraph": "TextContent"
+    "Paragraph": "TextContent",
+    "Snackbar": "Toast",
+    "Text box": "TextInput",
+    "Big text box": "TextArea",
+    "Comment box": "TextArea",
+    "Tick box": "Checkbox",
+    "Option buttons": "RadioButtons",
+    "Date selector": "Date",
+    "Time selector": "Time",
+    "Phone number": "Phone",
+    "Email address": "Email",
+    "Website link": "URL",
+    "Web link": "URL",
+    "File uploader": "Attachment",
+    "Upload button": "Attachment",
+    "Form buttons": "ActionButtons",
+    "Submit and cancel buttons": "ActionButtons",
+    "Buttons at the bottom": "ActionButtons",
+    "Error messages": "AlertBanner",
+    "Error banner": "AlertBanner",
+    "Validation messages": "AlertBanner",
+    "Form title": "AssignmentHeader",
+    "Step title": "AssignmentHeader",
+    "Popup message": "Toast",
+    "Notification message": "Toast",
+    "Stage progress": "Stages",
+    "Step navigation": "MultiStep",
+    "Task list": "ToDo",
+    "To do list": "ToDo"
   },
   "behaviorClasses": {
     "free text entry": ["TextInput"],
@@ -289,6 +340,9 @@
     "link display": ["SemanticLink"],
     "grouped set of fields": ["Group", "FieldGroup", "FieldGroupList"],
     "confirmation or alert message": ["CancelAlert", "AlertBanner", "Banner"],
+    "short notification after an action": ["Toast"],
+    "assignment step title": ["AssignmentHeader"],
+    "step progress indicator": ["MultiStep", "Stages"],
     "layout container": ["DefaultForm", "OneColumn", "TwoColumn", "NarrowWide", "WideNarrow"],
     "tabular list": ["SimpleTable", "ListView"],
     "selectable card": ["SelectableCard"],

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

@@ -4,7 +4,7 @@ ai-description: 'Design Profile template — defines the structure and schema fo
 
 # Design Profile Schema
 
-This document defines the required structure for a Design Profile produced by the `{{SKILL_DIR}}/embedded-flow/analyze-customer-repo.md` skill. The profile is consumed by the `{{PROMPT_DIR}}/generate-embedded-components{{PROMPT_EXT}}` prompt to generate Pega components matching the customer's application.
+This document defines the required structure for a Design Profile produced by the `{{SKILL_DIR}}/embedded-flow/analyze-customer-repo{{SKILL_EXT}}` skill. The profile is consumed by the `{{PROMPT_DIR}}/generate-embedded-components{{PROMPT_EXT}}` prompt to generate Pega components matching the customer's application.
 
 ---
 
@@ -63,11 +63,20 @@ Organize by category. Use semantic names where the customer defines them; otherw
 
 - Responsive boundaries (if defined)
 
+**Global Appearance:**
+
+- Font loading — where the web font is loaded and the family names it provides
+- Base text — the element or wrapper that sets base font family, size, line height, text colour, and page background
+- Reset or baseline — any global reset, normalizer, or baseline styles, and where they apply
+- Theme scope — the design system's root theme or provider wrapper, where it is mounted, and what it covers
+- Theme switching — supported themes and how the active one is selected
+- Overlay placement — whether dialogs, drawers, and popovers render inside the application root or outside the theme scope
+
 ---
 
 ### 3. Component Patterns
 
-Document how the customer's existing components work. **This section is context, not instructions.** Only the Validation Display and Styling conventions below are replicated in generated Pega components, because they affect appearance. The Input Interface, State Management, and Event Handling conventions are recorded so the reader understands the codebase — generated components follow the Pega contract for all three regardless of what is written here.
+Document how the customer's existing components work. **This section is context, not instructions.** Only the Validation Display, Styling, and Form Layout conventions below are replicated in generated Pega components, because they affect appearance. The Input Interface, State Management, and Event Handling conventions are recorded so the reader understands the codebase — generated components follow the Pega contract for all three regardless of what is written here.
 
 **Input Interface Convention:**
 
@@ -101,6 +110,19 @@ Record the visual treatment only. Generated components read validation messages
 - How conditional/dynamic styles are _expressed_ (e.g., error, disabled, focus states) — record the visual mechanism only; Pega supplies the state itself
 - How responsive behavior is implemented
 
+**Form Layout Convention:**
+
+Record the visual arrangement only. Generated layout templates own the space between fields, so capture what that space _is_ in the customer's forms.
+
+- Vertical gap between fields and horizontal gap between columns (as spacing tokens)
+- Label position (above, beside, floating)
+- Field width (fills its column, fixed, or maximum width)
+- How sections and groups of fields are separated, and the spacing around them
+- How multi-column forms are built, and the width at which they stack into one column
+- Space between the last field and the form's buttons, and button alignment
+- Whether gaps come from the form's layout container or from margins on each field
+- File paths of the forms these were taken from
+
 ---
 
 ### 4. File Conventions
@@ -148,8 +170,8 @@ List 3–5 components that were analyzed, with their file paths. These serve as
 The generation prompt reads this profile once at the start of component generation. It uses:
 
 - **Project Fundamentals** → to determine which SDK adapter to reference and what language to generate
-- **Design Tokens** → to apply correct colors, spacing, typography without hardcoding values
-- **Component Patterns** → to replicate the customer's validation display and styling conventions; the rest of the section is context only
+- **Design Tokens** → to apply correct colors, spacing, typography without hardcoding values; **Global Appearance** → to keep the Pega area inside the host's font and theme scope
+- **Component Patterns** → to replicate the customer's validation display, styling, and form layout conventions; the rest of the section is context only
 - **File Conventions** → to inform co-located files (barrels, tests, styles); generated components' paths and names come from Pega, not from here
 - **Import Conventions** → to write imports that match the project's style
 - **Representative Examples** → as reference sources to re-read for detailed pattern matching

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

@@ -2,6 +2,18 @@
 ai-description: Generate components across multiple types (field, template, widget, designSystemExtension, infra) using any design system
 ---
 
+## Progress milestones
+
+Announce these to the user as you reach them, in plain words and with a counter — "Step 5 of 6 — Building the components". Count only the milestones that apply to this run.
+
+1. **Understanding your request** — Step 0
+2. **Connecting to your Pega server** — Step 0.5.0
+3. **Choosing what to build** — Steps 0.5.1 to 0.5.7
+4. **Preparing your design system** — Steps 1 to 3
+5. **Building the components** — Steps 4 to 8, counting each component across the whole generation set
+6. **Checking the app builds** — Step 9
+7. **Trying it out** — Step 10
+
 ## Step 0 — Resolve inputs
 
 Read the user's message carefully. Extract:
@@ -14,11 +26,11 @@ Both **design system** and **base components folder** are required. If either is
 
 ⛔ **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.
+**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. The one exception is the portal shell (Step 0.5.4a): the components that draw the portal's frame are always included, even when the type scope leaves their type out.
 
-Example questions (ask only the ones that are actually missing):
+Ask every missing item together, in one plain message. 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)
+1. Which style kit should I use for the screens? (A style kit is a ready-made set of buttons, inputs, and layouts.) Before asking, check the project's dependency list for UI libraries and list any you find first, marked as already in the project, then offer Ant Design, Chakra UI, Carbon, Radix UI, or another. Never choose one on the user's behalf, even when only one is installed.
 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
@@ -53,11 +65,11 @@ Once design system, base folder, and type scope are resolved, continue to Step 0
 
 ## 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.
+⛔ **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. The only fixed names are the portal shell companions and fallback that Step 0.5.4a defines.
 
 ### 0.5.0 — Ensure the Pega server connection is configured
 
-Before executing any data source below, read and execute `{{SKILL_DIR}}/connect-pega-server.md`. It is a no-op when the connection is already configured. Otherwise, it resolves existing values from the active MCP config, application `sdk-config.json`, and environment files; asks once for every missing non-secret value; and writes chat-provided values to every applicable file. It may pause for an environment-sourced Pega MCP client secret (Cursor only) or an MCP reconnect. After the user retries, rerun the gate before executing any data source.
+Before executing any data source below, read and execute `{{SKILL_DIR}}/connect-pega-server{{SKILL_EXT}}`. It is a no-op when the connection is already configured. Otherwise, it resolves existing values from the active MCP config, application `sdk-config.json`, and environment files; asks once for every missing non-secret value; and writes chat-provided values to every applicable file. It may pause for an environment-sourced Pega MCP client secret (Cursor only — an MCP entry that carries its own client ID and secret) or an MCP reconnect. After the user retries, rerun the gate before executing any data source.
 
 ### 0.5.1 — Resolve the portal
 
@@ -67,6 +79,8 @@ Execute it directly, by name. An execution tool may instruct you to look up the
 
 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.
 
+Say it in plain words — for example: "I can't reach your Pega server from this chat. Usually the Pega connection in your editor isn't running, or it was started after this chat began. Start it, or open a new chat, and ask me again."
+
 If the execution runs but fails, report the failure and the error the server returned. You may list the server's advertised data sources alongside it as context, but never present that list as evidence the data page is unavailable. Do not substitute a different data page.
 
 The response's `pxResults` array holds one entry per portal. Then:
@@ -80,6 +94,8 @@ The response's `pxResults` array holds one entry per portal. Then:
 
 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.
 
+Explain the choices in plain words when you ask: **Landing pages** are the main screens people open from the app's menu, such as dashboards, lists, and home pages; **Cases** are the step-by-step forms people fill in to get work done, such as a service request; **Both** covers all of them.
+
 - 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.
@@ -92,7 +108,7 @@ Execute it — and every data page this step dispatches to — by name. Step 0.5
 
 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.
+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. Next to each class, also say in plain words whether the entry is a view or a landing page. This is a gate.
 
 For **each selected page**, resolve its components by its `pxObjClass`:
 
@@ -125,9 +141,26 @@ Present the returned case types as a **checkbox list** and let the user select o
 
 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.4a — Portal shell (always runs)
+
+The portal is drawn by a shell view that sits around every landing page and case. Its components are never returned by Step 0.5.3 or Step 0.5.4, and without them the portal shows a placeholder instead of its header and navigation. Run this step every time, whatever the user chose in Step 0.5.2.
+
+Execute **`D_pyViewDependencies`** with `ViewName = pzWebChannelInterfaceShell` and `ViewClass = Data-Portal`. Pass both values exactly as written — this view is part of the Pega platform, is the same for every portal type, and does not vary between installations. Read component names from `pxDependencies` and discard malformed entries. Execute it by name; Step 0.5.1's rule still applies.
+
+Then add these two, which the server never returns because `AppShell` looks them up from the registry at runtime:
+
+- **`WssNavBar`** — the top navigation bar of a self-service portal
+- **`AlertBanner`** — the page messages shown above the portal content
+
+Do not add `NavBar` — the SDK already provides it.
+
+If the execution fails or `pxDependencies` is empty, report it with the error the server returned, use `AppShell`, `WssNavBar`, and `AlertBanner` as the shell set, and tell the user this fallback was used. Do not stop the flow for this.
+
+Note each of these components as coming from the portal shell — Step 0.5.5 shows them as their own group and Step 9 reports them.
+
 ### 0.5.5 — Resolve names, 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.
+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. Add the portal shell names from Step 0.5.4a to that union; they go through the same name resolution below.
 
 Every component you generate must correspond to one canonical component listed in `{{PROMPT_DIR}}/component-manifest.json`. Pega defines a fixed set of components, and the manifest is the complete list of them. Read it once. It contains three things you need here:
 
@@ -135,6 +168,8 @@ Every component you generate must correspond to one canonical component listed i
 - `aliases` — known non-canonical names and the canonical name each one maps to
 - `behaviorClasses` — a fixed list of behaviour descriptions, each mapping to one or more canonical names
 
+**Not supported yet.** `GenAICoach` is not supported by the SDK yet. Whichever step returned it, do not run it through the stages below and do not ask the user about it. Keep it visible in the list, unticked and not selectable, with the plain reason "The SDK doesn't support this one yet", and never generate it. The portal shell entries Pega already provides — `ModalViewContainer`, `View`, and `ViewContainer` — are also set aside before the stages and shown as not generatable.
+
 For each name the server returned, work through the following stages in order. Stop at the first stage that produces an answer. These names come from Pega's own view metadata, so most are already canonical and settle at Stage 1 — the later stages exist for the ones that do not.
 
 #### Stage 1 — Normalized name match
@@ -154,13 +189,13 @@ Do not search for a "similar sounding" name here. Follow these three sub-steps e
 
 1. Decide what the component does for the end user, and choose **exactly one** entry from the `behaviorClasses` list that describes that behaviour. You must pick one of the listed classes. If you cannot honestly place the component in any of them, go to Stage 4.
 2. Read the canonical names that class maps to. If the class maps to exactly one name, that is the candidate.
-3. Read the candidate's skill file — `{{SKILL_DIR}}/{type}-skills/<CanonicalName>.md`, where `{type}` is `field`, `template`, `widget`, `design-system-extension`, or `infra` — and confirm its behavioural contract covers what the component does. If it clearly does not, go to Stage 4.
+3. Read the candidate's skill file — `{{SKILL_DIR}}/{type}-skills/<CanonicalName>{{SKILL_EXT}}`, where `{type}` is `field`, `template`, `widget`, `design-system-extension`, or `infra` — and confirm its behavioural contract covers what the component does. If it clearly does not, go to Stage 4.
 
 If the class maps to more than one canonical name, choose between them using the page or case type the name came from and the surrounding context. If the context does not make the choice obvious, go to Stage 4.
 
 #### Stage 4 — Ask the user
 
-Tell the user the name could not be resolved to a Pega component, list the two or three canonical names you considered most likely, and ask which one they want — or whether to leave it out. Do not guess, and do not proceed with that component until they answer. Collect every unresolved name into a **single** question rather than asking once per name; a portal can return a long list, and one question per name is not a usable gate.
+Tell the user the name could not be resolved to a Pega component, list the two or three canonical names you considered most likely, and ask which one they want — or whether to leave it out. Show each candidate as `<ComponentName> – plain description` (the first summary line of its skill file, reworded into a few plain words), for example "SimpleTableManual – Table you can edit". Do not guess, and do not proceed with that component until they answer. Collect every unresolved name into a **single** question rather than asking once per name; a portal can return a long list, and one question per name is not a usable gate.
 
 #### Rules for this step
 
@@ -171,7 +206,11 @@ Tell the user the name could not be resolved to a Pega component, list the two o
 
 Group the resolved canonical names by type — `field`, `template`, `widget`, `designSystemExtension`, or `infra`.
 
-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.
+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. Give that reason in plain words — for example, "Pega already provides this one".
+
+Show every entry as `<ComponentName> – plain description` — the name first, then the first summary line of its skill file reworded into a few plain words, for example "SimpleTableManual – Table you can edit" or "Date – Pick a date from a calendar". Label each group in plain words with the type in brackets: form fields (field), page layouts (template), panels (widget), display pieces (designSystemExtension), buttons and progress bars (infra).
+
+Show the portal shell components from Step 0.5.4a first, as their own group labelled in plain words — for example "Portal frame — header, navigation, and messages" — with every generatable entry **already ticked**. Say why they are included: the portal needs them to draw its frame on every page, whatever else is chosen. If the user unticks a shell entry, warn them once, in plain words, that the portal will show a placeholder instead of that part of its frame, then go with their answer.
 
 ⛔ **Wait for the user's answer.** This is a gate, not a notification. Nothing is read, installed, or written until the selection is confirmed.
 
@@ -180,6 +219,7 @@ Present the grouped list — noting, for any component contributed by more than
 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.
+- **`AlertBanner`**, **`AssignmentHeader`**, and **`Toast`** — whenever **Cases** was chosen in Step 0.5.2. The SDK draws the validation and page messages, the step title, and the short failure messages of every case assignment through them, and the server never returns them. Left ungenerated, the project keeps whatever design system they were previously built with.
 
 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.
 
@@ -187,7 +227,7 @@ Layout sub-variants are not part of the selection at all — Step 5.2.1 derives
 
 ### 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:
+Intersect the confirmed selection with the type scope from Step 0, group the result by type, and record it as **the generation set**. Portal shell components the user kept in Step 0.5.5 skip the intersection and always join the generation set; tell the user, in plain words, which ones were kept outside their chosen scope and why. The generation set 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.
@@ -195,7 +235,7 @@ Intersect the confirmed selection with the type scope from Step 0, group the res
 
 Generate nothing outside the generation set, with one exception: the registry dependencies that the selected components' own skill files declare. Some components are orchestrators — they render no control of their own and instead resolve other components from the registry at runtime, as reference and embedded data fields do. Those dependencies are building blocks rather than fields, so they never appear in view metadata and no data source above returns them, and a registry lookup that finds nothing degrades to a blank render rather than raising an error. Read each selected component's skill file, collect the registry keys it declares it will resolve, and add any that are neither already registered nor already in the set; repeat until the set stops growing, since a dependency's own skill may declare further ones. Report these additions in the Step 9 summary, naming which component required each.
 
-A dependency a skill file declares is required. A component you believe a portal might need is not — do not add components based on assumptions about what a portal might need.
+A dependency a skill file declares is required. A component you believe a portal might need is not — do not add components based on assumptions about what a portal might need. The portal shell from Step 0.5.4a is the one exception, because it is resolved from the platform's shell view rather than assumed.
 
 ---
 
@@ -203,13 +243,13 @@ A dependency a skill file declares is required. A component you believe a portal
 
 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                         |
-| --------------------- | ------------------------------------------ |
-| field                 | `{{SKILL_DIR}}/field-components.md`        |
-| 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`        |
+| Type                  | Skill file to read                                   |
+| --------------------- | ---------------------------------------------------- |
+| field                 | `{{SKILL_DIR}}/field-components{{SKILL_EXT}}`        |
+| template              | `{{SKILL_DIR}}/template-components{{SKILL_EXT}}`     |
+| widget                | `{{SKILL_DIR}}/widget-components{{SKILL_EXT}}`       |
+| designSystemExtension | `{{SKILL_DIR}}/design-system-extension{{SKILL_EXT}}` |
+| infra                 | `{{SKILL_DIR}}/infra-components{{SKILL_EXT}}`        |
 
 Keep all loaded skill files active throughout the entire session.
 
@@ -281,6 +321,8 @@ 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.
 
+**Say it in plain words.** Name each existing piece exactly as the user did — if they said "date picker", write "date picker", never a synonym or the component name. For pieces the user did not name, use `<ComponentName> – plain description` (the first summary line of its skill file, reworded into a few plain words). Group them under plain type labels (form fields, page layouts, panels, display pieces, buttons and progress bars). For example: _"You already have 6 form fields and 2 page layouts. Replace them with new ones, keep yours, or stop?"_ — "replace" is **Overwrite all**, "keep" is **Skip existing**, "stop" is **Cancel**.
+
 ⚠️ **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.
 
 ---
@@ -293,7 +335,7 @@ Generate each field component in the generation set, in order:
 
 ### 4.1 — Read the component-specific skill file (MANDATORY — do not skip)
 
-Read the file `{{SKILL_DIR}}/field-skills/<ComponentName>.md` using your file reading tool. This step is **required** for every component that has a skill file — do not rely solely on the general `field-components.md`.
+Read the file `{{SKILL_DIR}}/field-skills/<ComponentName>{{SKILL_EXT}}` using your file reading tool. This step is **required** for every component that has a skill file — do not rely solely on the general `field-components.md`.
 
 After reading, extract and keep active:
 
@@ -332,7 +374,7 @@ Open the project's component map file (the file that maps component names to the
 
 ### 4.4 — Report progress
 
-After each component: "`<ComponentName>` ✓ — using `<DS component name>`"
+After each component, tell the user in plain words what is now ready, described by what it shows on screen, and how far along you are — for example: "Date picker field ready (5 of 23)".
 
 ---
 
@@ -344,7 +386,7 @@ Generate each template component in the generation set, in order:
 
 ### 5.1 — Read the component-specific skill file (MANDATORY — do not skip)
 
-Read the file `{{SKILL_DIR}}/template-skills/<ComponentName>.md` using your file reading tool. This step is **required** for every component — do not rely solely on the general `template-components.md`.
+Read the file `{{SKILL_DIR}}/template-skills/<ComponentName>{{SKILL_EXT}}` using your file reading tool. This step is **required** for every component — do not rely solely on the general `template-components.md`.
 
 After reading, extract and keep active:
 
@@ -395,7 +437,7 @@ Open the project's component map file and:
 
 ### 5.4 — Report progress
 
-After each component: "`<ComponentName>` ✓ — `<Layout | Form | Page>` template"
+After each component, tell the user in plain words what is now ready, described by what it shows on screen, and how far along you are — for example: "Two-column page layout ready (9 of 23)".
 
 ---
 
@@ -407,7 +449,7 @@ Generate each widget component in the generation set, in order:
 
 ### 6.1 — Read the component-specific skill file (MANDATORY — do not skip)
 
-Read the file `{{SKILL_DIR}}/widget-skills/<ComponentName>.md` using your file reading tool. This step is **required** for every component that has a skill file — do not rely solely on the general `widget-components.md`.
+Read the file `{{SKILL_DIR}}/widget-skills/<ComponentName>{{SKILL_EXT}}` using your file reading tool. This step is **required** for every component that has a skill file — do not rely solely on the general `widget-components.md`.
 
 After reading, extract and keep active:
 
@@ -444,7 +486,7 @@ Open the project's component map file and:
 
 ### 6.4 — Report progress
 
-After each component: "`<ComponentName>` ✓ — using `<DS card/list primitive>`"
+After each component, tell the user in plain words what is now ready, described by what it shows on screen, and how far along you are — for example: "Attachments panel ready (14 of 23)".
 
 ---
 
@@ -456,11 +498,11 @@ Generate each design system extension component in the generation set, in order:
 
 ### 7.1 — Read the component-specific skill file (MANDATORY — do not skip)
 
-Read the file `{{SKILL_DIR}}/design-system-extension-skills/<ComponentName>.md` using your file reading tool. This step is **required** for every component that has a skill file — do not rely solely on the general `design-system-extension.md`.
+Read the file `{{SKILL_DIR}}/design-system-extension-skills/<ComponentName>{{SKILL_EXT}}` using your file reading tool. This step is **required** for every component that has a skill file — do not rely solely on the general `design-system-extension.md`.
 
 After reading, extract and keep active:
 
-- **Pattern classification** — B (Pure display) / A (PConnect display) / C (Complex display)
+- **Pattern classification** — B (Pure display) / A (Data display) / C (Complex display)
 - **Behavioral Contract** — prop handling, variant mapping, rendering logic, edge cases
 - **Design System Mapping** table — the recommended DS primitive (Pattern B components only)
 
@@ -474,7 +516,7 @@ Create the directory `<base>/designSystemExtension/<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 `design-system-extension.md` (loaded in Step 1). That file specifies the pattern variants (pure display, PConnect display, complex display) for this project's framework.
+Follow the implementation structure described in `design-system-extension.md` (loaded in Step 1). That file specifies the pattern variants (pure display, data display, complex display) for this project's framework.
 
 Apply the Behavioral Contract from the component skill file (prop handling, variant mapping, rendering logic, edge cases).
 
@@ -489,7 +531,7 @@ Open the project's component map file and:
 
 ### 7.4 — Report progress
 
-After each component: "`<ComponentName>` ✓ — Pattern `<B/A/C>`"
+After each component, tell the user in plain words what is now ready, described by what it shows on screen, and how far along you are — for example: "Message banner ready (18 of 23)".
 
 ---
 
@@ -511,7 +553,7 @@ Generate each infra component in the generation set that is one of the three ove
 
 ### 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`.
+Read the file `{{SKILL_DIR}}/infra-skills/<ComponentName>{{SKILL_EXT}}` 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:
 
@@ -556,7 +598,7 @@ Open the project's component map file and apply the case that matches what you f
 
 ### 8.4 — Report progress
 
-After each component: "`<ComponentName>` ✓ — `<display-only | case-aware | container>` chrome"
+After each component, tell the user in plain words what is now ready, described by what it shows on screen, and how far along you are — for example: "Submit and Cancel buttons ready (22 of 23)".
 
 ---
 
@@ -587,7 +629,14 @@ 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
+- `FieldValueList`, `AlertBanner`, `AssignmentHeader`, and `Toast`, for each one added automatically under Step 0.5.6
+- The portal shell components from Step 0.5.4a — which came from the server's shell view, which were added as companions, whether the fallback set was used, and any kept outside the type scope
 - All entries added to the component map
-- Any components skipped (if "skip existing" was chosen in Step 3, or because they are SDK-provided infrastructure)
+- Any components skipped (if "skip existing" was chosen in Step 3, because they are SDK-provided infrastructure, or because the SDK doesn't support them yet, such as `GenAICoach`)
 - Any name the server returned that resolved to a **different** canonical name, with the stage that produced the match (normalized name, alias, behaviour class, or the user's choice). Say it in your reply as well — the user must never discover a substitution only by reading the generated files
+
+---
+
+## Step 10 — Try the portal
+
+Once the Step 9 build passes, read and execute `{{SKILL_DIR}}/portal-flow/run-and-verify-portal{{SKILL_EXT}}`. Hand it the generation set with the page or case type each component came from, the portal resolved in Step 0.5.1, and the case types selected in Step 0.5.4 — when Cases was not chosen, it asks the user which case types to walk through. Report its verification summary together with the Step 9 summary.