@pega/sdk 0.0.13 → 0.0.15

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

@@ -2,59 +2,71 @@
 ai-description: Generate all (or a subset of) design system extension components using any design system
 ---
 
+## Progress milestones
+
+Announce these to the user as you reach them, in plain words and with a counter — "Step 3 of 4 — Building the components". 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 components** — Step 4, counting each component
+4. **Checking the app builds** — Step 5
+5. **Trying it out** — Step 6
+
 ## 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 DSE components should be generated (e.g. `src/components/designSystemExtension/`)
-- **Component list** — which components to generate (default: all 11 listed below)
+- **Component list** — which components to generate (default: all 13 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):
+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. Where should the DSE components be generated? (e.g. `src/components/designSystemExtension/`)
 
-If the user specified a subset (e.g., "just AlertBanner and FieldValueList"), restrict the list accordingly.
+If the user specified a subset (e.g., "just AlertBanner and FieldValueList"), restrict the list accordingly. The user may name components in everyday words ("error messages", "form title") — resolve each through the `aliases` and `behaviorClasses` in `{{PROMPT_DIR}}/component-manifest.json`, and confirm the resolved names with the user before continuing.
 
 Once both are known, continue to Step 1.
 
-### Full component list (default — 11 DSE components)
-
-| Component         | Pattern              | DS needed?    |
-| ----------------- | -------------------- | ------------- |
-| AlertBanner       | B — Pure display     | Yes           |
-| Banner            | B — Pure display     | Yes           |
-| CaseSummaryFields | A — PConnect display | Minimal       |
-| DetailsFields     | A — PConnect display | Minimal       |
-| FieldGroup        | C — Complex display  | No            |
-| FieldGroupList    | C — Complex display  | No            |
-| FieldValueList    | A — PConnect display | No (CSS only) |
-| Operator          | B — Pure display     | Yes           |
-| Pulse             | C — Complex display  | No            |
-| RichTextEditor    | C — Complex display  | No            |
-| WssQuickCreate    | B — Pure display     | Yes           |
+### Full component list (default — 13 DSE components)
+
+| Component         | Pattern             | DS needed?    |
+| ----------------- | ------------------- | ------------- |
+| AlertBanner       | B — Pure display    | Yes           |
+| AssignmentHeader  | B — Pure display    | Yes           |
+| Banner            | B — Pure display    | Yes           |
+| CaseSummaryFields | A — Data display    | Minimal       |
+| DetailsFields     | A — Data display    | Minimal       |
+| FieldGroup        | C — Complex display | No            |
+| FieldGroupList    | C — Complex display | No            |
+| FieldValueList    | A — Data display    | No (CSS only) |
+| Operator          | B — Pure display    | Yes           |
+| Pulse             | C — Complex display | No            |
+| RichTextEditor    | C — Complex display | No            |
+| Toast             | B — Pure display    | Yes           |
+| WssQuickCreate    | B — Pure display    | Yes           |
 
 ---
 
 ## Step 1 — Read `design-system-extension.md` (once, for the entire session)
 
-Read the full contents of `{{SKILL_DIR}}/design-system-extension.md`.
+Read the full contents of `{{SKILL_DIR}}/design-system-extension{{SKILL_EXT}}`.
 
 This gives you:
 
-- All three implementation patterns (Pure display, Field value display, Complex display with PConnect)
+- All three implementation patterns (Pure display, Field value display, Complex display)
 - The Design System Adaptation section — pattern categorisation, variant mapping table, DS discovery guidance
 - Styling patterns — when to use CSS files vs DS style props
 - Registration conventions
 
 Keep this context active throughout the entire generation session. Do not re-read it per component.
 
-> Pattern A/C components (FieldValueList, FieldGroup, Pulse, etc.) use PConnect bridge or plain CSS — they do not use the DS API. Only Pattern B components consume DS primitives.
+> Pattern A/C components (FieldValueList, FieldGroup, Pulse, etc.) use plain CSS or semantic HTML around what they are given — they do not use the DS API, and none of them calls `getPConnect()` itself. Only Pattern B components consume DS primitives.
 
 ---
 
@@ -113,6 +125,8 @@ If **any** exist, report them all at once and ask:
 
 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 "error messages", write "error messages", 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). For example: _"You already have error messages and a form title. Replace them with new ones, keep yours, or stop?"_ — "replace" is **Overwrite all**, "keep" is **Skip existing**, "stop" is **Cancel**.
+
 ---
 
 ## Step 4 — Generate each component (loop)
@@ -121,11 +135,11 @@ 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}}/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)
 
@@ -139,7 +153,7 @@ 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 `design-system-extension.md` (loaded in Step 1) for the component's pattern classification — B (Pure display), A (PConnect display), or C (Complex display) — as identified in Step 4a. That file specifies the framework-specific approach for each pattern. Pattern B components should use the DS display primitive you identified in Step 2.
+Follow the implementation structure described in `design-system-extension.md` (loaded in Step 1) for the component's pattern classification — B (Pure display), A (Data display), or C (Complex display) — as identified in Step 4a. That file specifies the framework-specific approach for each pattern. Pattern B components should use the DS display primitive you identified in Step 2.
 
 Apply the Behavioral Contract from the component skill file (exact props, variant logic, edge cases).
 
@@ -156,10 +170,16 @@ Do not reorder or restructure any existing entries.
 
 ### 4d — Report progress
 
-After each component: "`<ComponentName>` ✓ — Pattern `<B/A/C>`<`, using <DS primitive>` if Pattern B>"
+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 (1 of 13)".
 
 ---
 
 ## Step 5 — Verify the build
 
 Run the project's build process to confirm everything compiles without errors. Fix any build errors before reporting completion. Report a summary: list of all files created and all entries added to the component map.
+
+---
+
+## Step 6 — Try the portal
+
+Once the Step 5 build passes, read and execute `{{SKILL_DIR}}/portal-flow/run-and-verify-portal{{SKILL_EXT}}`, handing it the components you generated. Report its verification summary together with the Step 5 summary.

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

@@ -2,6 +2,14 @@
 ai-description: "Generate Pega components styled to match a customer's existing application — given a component list and a Design Profile, produces a generated components folder (location chosen by the user during analysis) with implementations that satisfy the Pega behavioral contract while rendering with the customer's design system, tokens, and styling approach, and reading like their own code"
 ---
 
+## Progress milestones
+
+When this prompt runs as part of the Embedded Flow Expert's full flow, announce that flow's milestones instead of these. Run on its own, announce these to the user as you reach them, in plain words and with a counter — "Step 2 of 3 — Building the form pieces".
+
+1. **Getting ready** — Steps 0 to 3
+2. **Building the form pieces** — Steps 4 to 5.1. After each component, say what is now ready and count it — "Date picker field ready (4 of 12)"
+3. **Checking the pieces** — Step 6
+
 ## Step 0 — Resolve missing information
 
 Read the user's message carefully. Extract:
@@ -10,17 +18,20 @@ Read the user's message carefully. Extract:
 - **Design Profile location** — always `docs/design-profile.md` at the project root. This location is fixed and never moves with the output path
 - **Output path** — read the **Output Path** field from Section 1 of the Design Profile and use it verbatim as `{output_path}`. Never re-ask for it and never fall back to a hardcoded default — it was already resolved once, with the user, during analysis
 
-The **component list** is required. If it is not provided and cannot be inferred from prior conversation context, stop and ask the user.
+The **component list** is required. If it is not provided and cannot be inferred from prior conversation context, stop and ask the user. Ask in plain words — "Which pieces do you want? Describe them in your own words, like 'date picker' or 'the buttons at the bottom'." Step 1 turns those words into component names.
 
-Two components are required whether or not the list names them. Add them silently and note the addition in the summary report:
+Five components are required whether or not the list names them. Add them silently and note the addition in the summary report:
 
 - **`FieldValueList`** — when the list contains any field component. Every field renders its display-only mode through it
 - **`ActionButtons`** — always. Every assignment renders action controls, and leaving it ungenerated puts SDK-styled buttons in the middle of the customer's form
+- **`AlertBanner`** — always. The assignment shows validation errors and page messages through it, and leaving it ungenerated hides them entirely
+- **`AssignmentHeader`** — always. The SDK draws the step title above the form through it
+- **`Toast`** — always. The SDK shows short failure messages after an action through it
 
 If no Design Profile exists at the expected location:
 
-- Ask the user: "No Design Profile found. Should I analyze your codebase first to create one?"
-- If yes, execute the `{{SKILL_DIR}}/embedded-flow/analyze-customer-repo.md` skill first, then return here.
+- Ask the user: "No Design Profile found. Should I analyze your codebase first to create one?" Say it in plain words — for example "I haven't learned how your app looks yet. Shall I look through your app first, so the new pieces match it?"
+- If yes, execute the `{{SKILL_DIR}}/embedded-flow/analyze-customer-repo{{SKILL_EXT}}` skill first, then return here.
 
 ---
 
@@ -59,7 +70,7 @@ If the class maps to more than one canonical name, choose between them using the
 
 ### Stage 4 — Ask the user
 
-Tell the user that the requested name is not a Pega component name, list the two or three canonical names you considered most likely, and ask which one they want. Do not guess, and do not proceed with that component until they answer.
+Tell the user that the requested name is not a Pega component name, list the two or three canonical names you considered most likely, and ask which one they want. Say it plainly — for example "I'm not sure which piece you mean by 'slider box'. Did you mean one of these?" — and 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.
 
 ### Rules for this step
 
@@ -81,13 +92,13 @@ Read the following **once** before the generation loop:
 
 2. **General type-level skills** — for each component type present in the grouped list, read the corresponding general skill:
 
-   | Type                    | 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`        |
+   | Type                    | 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}}`        |
 
    These establish the shared behavioral contract for each category.
 
@@ -130,7 +141,7 @@ For each component in the list, in the grouped order (fields first, then templat
 
 ### 4a. Read the component-specific skill
 
-Look for `{{SKILL_DIR}}/{type}-skills/{ComponentName}.md` where `{type}` is `field`, `template`, `widget`, `design-system-extension`, or `infra`.
+Look for `{{SKILL_DIR}}/{type}-skills/{ComponentName}{{SKILL_EXT}}` where `{type}` is `field`, `template`, `widget`, `design-system-extension`, or `infra`.
 
 If the file exists, read it fully. It defines:
 
@@ -156,6 +167,7 @@ Create the component implementation that satisfies **both**:
 2. **The customer's conventions** (from Design Profile):
    - Use the customer's UI library primitives for rendering
    - Follow the customer's styling approach (apply styles the way they do)
+   - Inherit the host's base font and text colour, and follow the Form Layout Convention — both governed by the Styling and Form Layout rules in the embedded component rules
    - Follow the customer's import conventions (aliases, grouping, named/default)
    - Use the customer's export style and co-located file layout (barrel files, types, styles)
 
@@ -178,6 +190,7 @@ Add an entry for this component in the registry file at `{output_path}/component
 
 - The key must be the canonical Pega component name (as resolved in Step 1)
 - The value must reference the generated component's export
+- **One exception — `ToDo`.** Register it under the key `Todo`, the name the Pega engine and the SDK request at runtime: `Todo: ToDo`. Its folder and file stay `ToDo/ToDo.*`. Registered as `ToDo`, the lookup finds nothing and the to-do panel silently does not render
 
 ---
 
@@ -195,7 +208,7 @@ After all components are generated, ensure the registry file (`{output_path}/com
    - **ActionButtons** — the Cancel/Save/Submit row at the bottom of an assignment
    - **Stages** — the case stage progress indicator
    - **MultiStep** — the step navigation within a multi-step assignment
-4. Every component from the input list must have a corresponding entry
+4. Every component from the input list must have a corresponding entry. If `ToDo` was generated, its entry is `Todo: ToDo` (see Step 4d)
 5. No `infra` component other than those three may appear in the generated output — the rest are always sourced from the SDK adapter package
 
 ---
@@ -309,6 +322,6 @@ Whenever `Requested Name` and `Resolved As` differ, say so in your reply as well
 6. **One folder per component** — each component gets its own folder named after its canonical Pega name; paths are Pega's, contents are the customer's
 7. **Preserve SDK bridge contract** — the component must work with the SDK bridge component's resolution and rendering mechanism; the input interface defined in the skill file is non-negotiable
 8. **Only canonical components exist** — every generated component must correspond to a canonical name in the component manifest, and every registry key must be that canonical name. Never create a component for a name that is not in the manifest, and never add the user's original wording as an extra registry key or alias. Pega resolves components by its own naming standard, so a non-canonical key would never be requested at runtime.
-9. **Never generate infrastructure components, except the three overridable chrome components** — `ActionButtons`, `MultiStep`, and `Stages` may be generated into `{output_path}/infra/` and registered as overrides, because they render inline with the case form and must match the customer's UI. They are not interchangeable: `ActionButtons` and `MultiStep` are **assignment** chrome and belong in an embedded flow, whereas `Stages` is **case** chrome that only appears on a case-view surface and must not be generated for an embedded flow. Every other component categorized as `infra` in the component manifest (NavBar, DeferLoad, VerticalTabs, DashboardFilter) is provided by the SDK adapter package and must never be generated, overridden, or customized. If one of those appears in the input list, skip it and note in the summary report that it is SDK-provided.
+9. **Never generate infrastructure components, except the three overridable chrome components** — `ActionButtons`, `MultiStep`, and `Stages` may be generated directly under `{output_path}`, like every other component, and registered as overrides, because they render inline with the case form and must match the customer's UI. They are not interchangeable: `ActionButtons` and `MultiStep` are **assignment** chrome and belong in an embedded flow, whereas `Stages` is **case** chrome that only appears on a case-view surface and must not be generated for an embedded flow. Every other component categorized as `infra` in the component manifest (NavBar, DeferLoad, VerticalTabs, DashboardFilter) is provided by the SDK adapter package and must never be generated, overridden, or customized. If one of those appears in the input list, skip it and note in the summary report that it is SDK-provided.
 
 10. **Reproduce the chrome components' contract exactly** — read the skill file for `ActionButtons`, `MultiStep`, or `Stages` in `{{SKILL_DIR}}/infra-skills/` before generating it. Only the markup and styling change; props, callback signatures, and localization are fixed by the SDK.

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

@@ -2,6 +2,16 @@
 ai-description: Generate all (or a subset of) field components using any design system
 ---
 
+## Progress milestones
+
+Announce these to the user as you reach them, in plain words and with a counter — "Step 3 of 4 — Building the components". 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 components** — Step 4, counting each component
+4. **Checking the app builds** — Step 5
+5. **Trying it out** — Step 6
+
 ## Step 0 — Resolve inputs
 
 Read the user's message carefully. Extract:
@@ -14,12 +24,12 @@ Both **design system** and **output base path** are required. If either is missi
 
 ⛔ **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):
+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. Where should the field components be generated? (e.g. `src/components/field/`)
 
-If the user specified a subset (e.g., "just TextInput and Dropdown"), restrict the list accordingly.
+If the user specified a subset (e.g., "just TextInput and Dropdown"), restrict the list accordingly. The user may name components in everyday words ("date picker", "phone number") — resolve each through the `aliases` and `behaviorClasses` in `{{PROMPT_DIR}}/component-manifest.json`, and confirm the resolved names with the user before continuing.
 
 Once both are known, continue to Step 1.
 
@@ -59,7 +69,7 @@ Once both are known, continue to Step 1.
 
 ## Step 1 — Read `field-components.md` (once, for the entire session)
 
-Read the full contents of `{{SKILL_DIR}}/field-components.md`.
+Read the full contents of `{{SKILL_DIR}}/field-components{{SKILL_EXT}}`.
 
 This gives you:
 
@@ -133,6 +143,8 @@ If **any** exist, report them all at once and ask:
 
 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). For example: _"You already have a date picker and an email box. Replace them with new ones, keep yours, or stop?"_ — "replace" is **Overwrite all**, "keep" is **Skip existing**, "stop" is **Cancel**.
+
 ---
 
 ## Step 4 — Generate each component (loop)
@@ -141,7 +153,7 @@ 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}}/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:
 
@@ -181,10 +193,16 @@ Do not reorder or restructure any existing entries.
 
 ### 4d — 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 27)".
 
 ---
 
 ## Step 5 — Verify the build
 
 Run the project's build process to confirm everything compiles without errors. Fix any build errors before reporting completion. Report a summary: list of all files created and all entries added to the component map.
+
+---
+
+## Step 6 — Try the portal
+
+Once the Step 5 build passes, read and execute `{{SKILL_DIR}}/portal-flow/run-and-verify-portal{{SKILL_EXT}}`, handing it the components you generated. Report its verification summary together with the Step 5 summary.

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

@@ -2,6 +2,16 @@
 ai-description: Generate all (or a subset of) infrastructure (chrome) components using any design system
 ---
 
+## Progress milestones
+
+Announce these to the user as you reach them, in plain words and with a counter — "Step 3 of 4 — Building the components". 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 components** — Step 4, counting each component
+4. **Checking the app builds** — Step 5
+5. **Trying it out** — Step 6
+
 ## Step 0 — Resolve inputs
 
 Read the user's message carefully. Extract:
@@ -14,12 +24,12 @@ Both **design system** and **output base path** are required. If either is missi
 
 ⛔ **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):
+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. 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.
+If the user specified a subset (e.g., "just ActionButtons and Stages"), restrict the list accordingly. The user may name components in everyday words ("buttons at the bottom", "step navigation") — resolve each through the `aliases` and `behaviorClasses` in `{{PROMPT_DIR}}/component-manifest.json`, and confirm the resolved names with the user before continuing.
 
 ### Full component list (default — 3 infra components)
 
@@ -48,7 +58,7 @@ 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`.
+Read the full contents of `{{SKILL_DIR}}/infra-components{{SKILL_EXT}}`.
 
 This gives you:
 
@@ -133,6 +143,8 @@ If a component already has **files at the output path**, report them all at once
 
 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 "the buttons at the bottom", write that, 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). For example: _"You already have your own buttons at the bottom. Replace them with new ones, keep yours, or stop?"_ — "replace" is **Overwrite all**, "keep" is **Skip existing**, "stop" is **Cancel**.
+
 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.
 
 ---
@@ -143,7 +155,7 @@ 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`.
+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:
 
@@ -201,7 +213,7 @@ Never remove the SDK's built-in component spread — it supplies the infrastruct
 
 ### 4d — Report progress
 
-After each component: "`<ComponentName>` ✓ — `<display-only | case-aware | container>` chrome, using `<DS 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: "Submit and Cancel buttons ready (1 of 3)".
 
 ---
 
@@ -220,3 +232,9 @@ Before reporting success, confirm:
 - [ ] 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.
+
+---
+
+## Step 6 — Try the portal
+
+Once the Step 5 build passes, read and execute `{{SKILL_DIR}}/portal-flow/run-and-verify-portal{{SKILL_EXT}}`, handing it the components you generated. Report its verification summary together with the Step 5 summary.

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

@@ -2,6 +2,16 @@
 ai-description: Generate all (or a subset of) template components using any design system
 ---
 
+## Progress milestones
+
+Announce these to the user as you reach them, in plain words and with a counter — "Step 3 of 4 — Building the components". 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 components** — Step 4, counting each component
+4. **Checking the app builds** — Step 5
+5. **Trying it out** — Step 6
+
 ## Step 0 — Resolve inputs
 
 Read the user's message carefully. Extract:
@@ -14,14 +24,14 @@ Both **design system** and **output base path** are required. If either is missi
 
 ⛔ **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):
+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. Where should the template components be generated? (e.g. `src/components/template/`)
 
 > **Note:** The design system applies only to **layout templates** (TwoColumn, OneColumn, NarrowWide, WideNarrow, and their sub-variants). Form templates and page templates use the PConnect bridge pattern and are design-system agnostic — they will be generated without DS primitives regardless of your choice.
 
-If the user specified a subset (e.g., "just TwoColumn and OneColumn"), restrict the list accordingly.
+If the user specified a subset (e.g., "just TwoColumn and OneColumn"), restrict the list accordingly. The user may name components in everyday words ("page layouts", "two columns") — resolve each through the `aliases` and `behaviorClasses` in `{{PROMPT_DIR}}/component-manifest.json`, and confirm the resolved names with the user before continuing.
 
 Once both are known, continue to Step 1.
 
@@ -68,7 +78,7 @@ Once both are known, continue to Step 1.
 
 ## Step 1 — Read `template-components.md` (once, for the entire session)
 
-Read the full contents of `{{SKILL_DIR}}/template-components.md`.
+Read the full contents of `{{SKILL_DIR}}/template-components{{SKILL_EXT}}`.
 
 This gives you:
 
@@ -139,6 +149,8 @@ If **any** exist, report them all at once and ask:
 
 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 "two-column layout", write "two-column layout", 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). For example: _"You already have a two-column layout. Replace it with a new one, keep yours, or stop?"_ — "replace" is **Overwrite all**, "keep" is **Skip existing**, "stop" is **Cancel**.
+
 ---
 
 ## Step 4 — Generate each component (loop)
@@ -147,7 +159,7 @@ 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}}/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:
 
@@ -218,10 +230,16 @@ Do not reorder or restructure any existing entries.
 
 ### 4d — Report progress
 
-After each component: "`<ComponentName>` ✓ — `<Layout | Form | Page>` template`<, using <DS component name> for grid>` if layout"
+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 (3 of 32)".
 
 ---
 
 ## Step 5 — Verify the build
 
 Run the project's build process to confirm everything compiles without errors. Fix any build errors before reporting completion. Report a summary: list of all files created and all entries added to the component map.
+
+---
+
+## Step 6 — Try the portal
+
+Once the Step 5 build passes, read and execute `{{SKILL_DIR}}/portal-flow/run-and-verify-portal{{SKILL_EXT}}`, handing it the components you generated. Report its verification summary together with the Step 5 summary.

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

@@ -2,6 +2,16 @@
 ai-description: Generate all (or a subset of) widget components using any design system
 ---
 
+## Progress milestones
+
+Announce these to the user as you reach them, in plain words and with a counter — "Step 3 of 4 — Building the components". 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 components** — Step 4, counting each component
+4. **Checking the app builds** — Step 5
+5. **Trying it out** — Step 6
+
 ## Step 0 — Resolve inputs
 
 Read the user's message carefully. Extract:
@@ -14,12 +24,12 @@ Both **design system** and **output base path** are required. If either is missi
 
 ⛔ **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):
+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. Where should the widget components be generated? (e.g. `src/components/widget/`)
 
-If the user specified a subset (e.g., "just ToDo and Attachment"), restrict the list accordingly.
+If the user specified a subset (e.g., "just ToDo and Attachment"), restrict the list accordingly. The user may name components in everyday words ("task list", "file uploader") — resolve each through the `aliases` and `behaviorClasses` in `{{PROMPT_DIR}}/component-manifest.json`, and confirm the resolved names with the user before continuing.
 
 Once both are known, continue to Step 1.
 
@@ -42,7 +52,7 @@ Once both are known, continue to Step 1.
 
 ## Step 1 — Read `widget-components.md` (once, for the entire session)
 
-Read the full contents of `{{SKILL_DIR}}/widget-components.md`.
+Read the full contents of `{{SKILL_DIR}}/widget-components{{SKILL_EXT}}`.
 
 This gives you:
 
@@ -118,6 +128,8 @@ If **any** exist, report them all at once and ask:
 
 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 "task list", write "task list", 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). For example: _"You already have a task list. Replace it with a new one, keep yours, or stop?"_ — "replace" is **Overwrite all**, "keep" is **Skip existing**, "stop" is **Cancel**.
+
 ---
 
 ## Step 4 — Generate each component (loop)
@@ -126,7 +138,7 @@ 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}}/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:
 
@@ -163,10 +175,16 @@ Do not reorder or restructure any existing entries.
 
 ### 4d — 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 (2 of 10)".
 
 ---
 
 ## Step 5 — Verify the build
 
 Run the project's build process to confirm everything compiles without errors. Fix any build errors before reporting completion. Report a summary: list of all files created and all entries added to the component map.
+
+---
+
+## Step 6 — Try the portal
+
+Once the Step 5 build passes, read and execute `{{SKILL_DIR}}/portal-flow/run-and-verify-portal{{SKILL_EXT}}`, handing it the components you generated. Report its verification summary together with the Step 5 summary.

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

@@ -87,6 +87,7 @@ Use the table below to map what you see in the image to SDK component names.
 | What you see                                                 | SDK component name  | Category              |
 | ------------------------------------------------------------ | ------------------- | --------------------- |
 | Coloured banner alert bar (info / warning / error / success) | `AlertBanner`       | designSystemExtension |
+| Step title text directly above an assignment's form fields   | `AssignmentHeader`  | designSystemExtension |
 | Hero-style banner with title + CTA button                    | `Banner`            | designSystemExtension |
 | Read-only field+value pairs in a case summary                | `CaseSummaryFields` | designSystemExtension |
 | Read-only label+value pairs in a details view                | `DetailsFields`     | designSystemExtension |
@@ -95,6 +96,7 @@ Use the table below to map what you see in the image to SDK component names.
 | User operator info popover (name + contact)                  | `Operator`          | designSystemExtension |
 | Comment/pulse card with avatar + timestamp                   | `Pulse`             | designSystemExtension |
 | Rich text editor with theme-aware toolbar                    | `RichTextEditor`    | designSystemExtension |
+| Short dark message at the screen edge with a close (×) icon  | `Toast`             | designSystemExtension |
 | Quick-create shortcut links list (WSS sidebar)               | `WssQuickCreate`    | designSystemExtension |
 
 ---