@pega/sdk 0.0.13 → 0.0.15

package/templates/angular-sdk-reference/src/components/templates/default-form/default-form.component.ts

@@ -0,0 +1,105 @@
+/**
+ * DefaultForm — renders form fields in a configurable grid layout (1/2/3 columns).
+ *
+ * Reads NumCols from config to determine grid layout. Children are the form field
+ * components rendered via PConnectBridge.
+ *
+ * Pattern reference: angular-sdk-components DefaultFormComponent + sdk-react DefaultForm
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Component, Input, ChangeDetectorRef, NgZone } from '@angular/core';
+import type { OnInit, OnDestroy } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { PegaBridgeService } from '@pega/sdk-angular';
+import { getInstructions } from '../../helpers/sdk-helpers';
+import type { Unsubscribe } from '@pega/sdk-angular';
+import { PConnectBridgeComponent } from '@pega/sdk-angular';
+
+@Component({
+  selector: 'pega-default-form',
+  standalone: true,
+  imports: [CommonModule, PConnectBridgeComponent],
+  template: `
+    <div
+      *ngIf="instructions"
+      style="margin-bottom: 0.75rem; color: #6b7280; font-size: 0.875rem;"
+      [innerHTML]="instructions"
+    ></div>
+    <div
+      [style.display]="'grid'"
+      [style.gridTemplateColumns]="gridColumns"
+      [style.gap]="'1rem'"
+    >
+      <div *ngFor="let getter of childGetters">
+        <pconnect-bridge [getPConnect]="getter"></pconnect-bridge>
+      </div>
+    </div>
+  `,
+})
+export class DefaultFormComponent implements OnInit, OnDestroy {
+  @Input() props: any;
+
+  gridColumns = 'repeat(1, minmax(0, 1fr))';
+  instructions = '';
+  childGetters: Array<() => typeof PConnect> = [];
+
+  private pConn: any;
+  private bridge = new PegaBridgeService();
+  private storeUnsub: Unsubscribe | undefined;
+
+  constructor(
+    private ngZone: NgZone,
+    private cdr: ChangeDetectorRef,
+  ) {}
+
+  ngOnInit(): void {
+    this.pConn = this.props.getPConnect();
+    this.updateSelf();
+
+    const subscription = this.bridge.observe(this.pConn).subscribe(() => {
+      this.updateSelf();
+    });
+    this.storeUnsub = () => subscription.unsubscribe();
+  }
+
+  ngOnDestroy(): void {
+    this.storeUnsub?.();
+  }
+
+  private updateSelf(): void {
+    const configProps = this.pConn.getConfigProps();
+    const numCols = configProps.NumCols ?? '1';
+    this.instructions =
+      getInstructions(this.pConn, configProps.instructions) ?? '';
+
+    switch (numCols) {
+      case '2':
+        this.gridColumns = 'repeat(2, 1fr)';
+        break;
+      case '3':
+        this.gridColumns = 'repeat(3, 1fr)';
+        break;
+      default:
+        this.gridColumns = 'repeat(1, minmax(0, 1fr))';
+        break;
+    }
+
+    // Children: first child's children are the actual form fields
+    const kids = this.pConn.getChildren?.() ?? [];
+    let fields: any[] = [];
+    if (kids.length > 0 && kids[0].getPConnect) {
+      fields = kids[0].getPConnect().getChildren?.() ?? [];
+    } else {
+      fields = kids;
+    }
+
+    this.childGetters = fields.map((child: any) => {
+      return child.getPConnect ?? (() => child);
+    });
+
+    this.ngZone.run(() => {
+      this.cdr.detectChanges();
+    });
+  }
+}

package/templates/angular-sdk-reference/src/components/templates/narrow-wide/narrow-wide.component.ts

@@ -0,0 +1,37 @@
+/**
+ * NarrowWide — narrow-left/wide-right two-column layout (1:2 ratio).
+ *
+ * Pattern reference: angular-sdk-components NarrowWideFormComponent + sdk-react NarrowWide
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Component, Input } from '@angular/core';
+import type { OnInit } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { PConnectBridgeComponent } from '@pega/sdk-angular';
+
+@Component({
+  selector: 'pega-narrow-wide',
+  standalone: true,
+  imports: [CommonModule, PConnectBridgeComponent],
+  template: `
+    <div style="display: grid; grid-template-columns: 1fr 2fr; gap: 1rem;">
+      <div *ngFor="let getter of childGetters">
+        <pconnect-bridge [getPConnect]="getter"></pconnect-bridge>
+      </div>
+    </div>
+  `,
+})
+export class NarrowWideComponent implements OnInit {
+  @Input() props: any;
+
+  childGetters: Array<() => typeof PConnect> = [];
+
+  ngOnInit(): void {
+    const pConn = this.props.getPConnect();
+    const children = pConn.getChildren?.() ?? [];
+    this.childGetters = children.map((child: any) => {
+      return child.getPConnect ?? (() => child);
+    });
+  }
+}

package/templates/angular-sdk-reference/src/components/templates/one-column/one-column.component.ts

@@ -0,0 +1,37 @@
+/**
+ * OneColumn — single-column layout template that renders children vertically.
+ *
+ * Pattern reference: angular-sdk-components OneColumnComponent + sdk-react OneColumn
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Component, Input } from '@angular/core';
+import type { OnInit } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { PConnectBridgeComponent } from '@pega/sdk-angular';
+
+@Component({
+  selector: 'pega-one-column',
+  standalone: true,
+  imports: [CommonModule, PConnectBridgeComponent],
+  template: `
+    <div style="display: flex; flex-direction: column; gap: 0.25rem;">
+      <div *ngFor="let getter of childGetters">
+        <pconnect-bridge [getPConnect]="getter"></pconnect-bridge>
+      </div>
+    </div>
+  `,
+})
+export class OneColumnComponent implements OnInit {
+  @Input() props: any;
+
+  childGetters: Array<() => typeof PConnect> = [];
+
+  ngOnInit(): void {
+    const pConn = this.props.getPConnect();
+    const children = pConn.getChildren?.() ?? [];
+    this.childGetters = children.map((child: any) => {
+      return child.getPConnect ?? (() => child);
+    });
+  }
+}

package/templates/angular-sdk-reference/src/components/templates/two-column/two-column.component.ts

@@ -0,0 +1,37 @@
+/**
+ * TwoColumn — two-column grid layout template.
+ *
+ * Pattern reference: angular-sdk-components TwoColumnComponent + sdk-react TwoColumn
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Component, Input } from '@angular/core';
+import type { OnInit } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { PConnectBridgeComponent } from '@pega/sdk-angular';
+
+@Component({
+  selector: 'pega-two-column',
+  standalone: true,
+  imports: [CommonModule, PConnectBridgeComponent],
+  template: `
+    <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 1rem;">
+      <div *ngFor="let getter of childGetters">
+        <pconnect-bridge [getPConnect]="getter"></pconnect-bridge>
+      </div>
+    </div>
+  `,
+})
+export class TwoColumnComponent implements OnInit {
+  @Input() props: any;
+
+  childGetters: Array<() => typeof PConnect> = [];
+
+  ngOnInit(): void {
+    const pConn = this.props.getPConnect();
+    const children = pConn.getChildren?.() ?? [];
+    this.childGetters = children.map((child: any) => {
+      return child.getPConnect ?? (() => child);
+    });
+  }
+}

package/templates/angular-sdk-reference/src/components/templates/wide-narrow/wide-narrow.component.ts

@@ -0,0 +1,37 @@
+/**
+ * WideNarrow — wide-left/narrow-right two-column layout (2:1 ratio).
+ *
+ * Pattern reference: angular-sdk-components WideNarrowFormComponent + sdk-react WideNarrow
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Component, Input } from '@angular/core';
+import type { OnInit } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { PConnectBridgeComponent } from '@pega/sdk-angular';
+
+@Component({
+  selector: 'pega-wide-narrow',
+  standalone: true,
+  imports: [CommonModule, PConnectBridgeComponent],
+  template: `
+    <div style="display: grid; grid-template-columns: 2fr 1fr; gap: 1rem;">
+      <div *ngFor="let getter of childGetters">
+        <pconnect-bridge [getPConnect]="getter"></pconnect-bridge>
+      </div>
+    </div>
+  `,
+})
+export class WideNarrowComponent implements OnInit {
+  @Input() props: any;
+
+  childGetters: Array<() => typeof PConnect> = [];
+
+  ngOnInit(): void {
+    const pConn = this.props.getPConnect();
+    const children = pConn.getChildren?.() ?? [];
+    this.childGetters = children.map((child: any) => {
+      return child.getPConnect ?? (() => child);
+    });
+  }
+}

package/templates/angular-sdk-reference/tsconfig.app.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/app",
+    "types": [],
+    "noPropertyAccessFromIndexSignature": false
+  },
+  "files": ["src/main.ts"],
+  "include": [
+    "src/**/*.d.ts",
+    "../../node_modules/@pega/pcore-pconnect-typedefs/index.d.ts"
+  ]
+}

package/templates/react-sdk-reference/.ai-common/agents/embedded-flow-expert.md

@@ -1,6 +1,6 @@
 ---
 ai-name: Embedded Flow Expert
-ai-description: "Use when the user wants to embed a Pega case flow into their existing application — analyzes their codebase, generates Pega components that render with their design system and read like their own code, and wires the integration. Handles trigger phrases like 'embed a case in my app', 'generate pega components for my app', 'analyze my design system', 'integrate pega into my application', 'create pega components matching my app'."
+ai-description: "Use when the user wants to embed a Pega case flow into their existing application — analyzes their codebase, generates Pega components that render with their design system and read like their own code, and wires the integration. Handles trigger phrases like 'embed a case in my app', 'generate pega components for my app', 'analyze my design system', 'integrate pega into my application', 'create pega components matching my app'. Also handles plain requests such as 'add the service request form to my app', 'show the Pega form inside my page', 'learn how my app looks', 'connect the form to my app', 'check the form works', and 'my app's look changed, update the form'."
 ---
 
 You are the **Embedded Flow Expert**. You help customers embed Pega case flows into their existing applications by:
@@ -19,17 +19,17 @@ You execute the workflows defined in this repository's skill and prompt files
 **If the user's message is vague, a greeting, or says "help"**, respond with:
 
 1. A one-paragraph summary of what you do (analyze customer apps, generate matching Pega components, wire integration).
-2. A bulleted menu of supported flows:
-   - **Analyze my app** — "scan my codebase and create a Design Profile"
-   - **Generate Pega components** — "generate these components matching my app's design system"
-   - **Full embedded flow** — "embed [case type] into my app" (runs analysis + generation + wiring + runtime verification)
-   - **Wire integration** — "how do I connect the generated components to my app"
-   - **Verify the integration** — "run my app and check the Pega flow works"
-   - **Update components** — "my design system changed, regenerate the pega components"
-3. Ask the user to clarify:
+2. A bulleted menu of supported flows. Lead each item with the plain label and keep the flow name in brackets:
+   - **Learn how my app looks** (Analyze my app) — "look at my app and note its style"
+   - **Build the form pieces in my app's style** (Generate Pega components) — "build a date picker and a dropdown that match my app"
+   - **Add a Pega form to my app, start to finish** (Full embedded flow) — "add the service request form to my app" (runs analysis + generation + wiring + runtime verification)
+   - **Connect the form to my app** (Wire integration) — "how do I connect the form to my app"
+   - **Check the form works** (Verify the integration) — "run my app and check the Pega form works"
+   - **Refresh the form pieces after a restyle** (Update components) — "my app's look changed, update the form"
+3. Ask the user to clarify (offer the plain labels above, then map the answer back to the flow name in brackets):
    - **Flow**: Analyze only | Generate components | Full embedded flow | Wire integration | Verify integration | Update/regenerate
-   - **Component list** (only for the standalone "Generate components" flow): the Pega component names to generate. Do not ask for this in the full embedded flow — Step 0 resolves it from the server
-   - **Case type** (only for "Full embedded flow"): the Pega case type to embed. If the user does not name one, do not press for it — Step 0 presents the case types the server returns
+   - **Component list** (only for the standalone "Generate components" flow): the Pega component names to generate. Ask for it in plain words — "Which pieces do you want? Describe them in your own words, like 'date picker' or 'the buttons at the bottom'" — and resolve each through the `aliases` and `behaviorClasses` in `{{PROMPT_DIR}}/component-manifest.json`, confirming the matches with the user. Do not ask for this in the full embedded flow — Step 0 resolves it from the server
+   - **Case type** (only for "Full embedded flow"): the Pega case type to embed. If the user does not name one, do not press for it — Step 0 presents the case types the server returns. The user may name it in plain words ("service request") — Step 0.2 matches that against the server's names
    - **Launch point and render target** (for "Full embedded flow" and "Wire integration"): what opens the case flow, and where it appears
 
 Do not start reading files or generating anything until intent and required inputs are confirmed.
@@ -38,16 +38,18 @@ Do not start reading files or generating anything until intent and required inpu
 
 Determine which workflow governs the request, then execute it by reading the referenced files.
 
-| Request shape                                                                                 | Action                                                                                                                                                                                                                                                  |
-| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "Analyze my app / scan my codebase / create a design profile"                                 | Read and execute `{{SKILL_DIR}}/embedded-flow/analyze-customer-repo.md`                                                                                                                                                                                 |
-| "Generate these Pega components for my app" (component list provided, Design Profile exists)  | Read and execute `{{PROMPT_DIR}}/generate-embedded-components{{PROMPT_EXT}}`                                                                                                                                                                            |
-| "Generate these Pega components for my app" (component list provided, NO Design Profile)      | Execute analysis first → then generation                                                                                                                                                                                                                |
-| "Embed [case type] in my app" / "Full embedded flow" / "Integrate pega sdk" / "open workflow" | Execute Step 0 (resolve the case type and components) → analysis → Step 0 of `{{SKILL_DIR}}/embedded-flow/wire-integration.md` → generation → the remaining wiring steps → verification per `{{SKILL_DIR}}/embedded-flow/run-and-verify-integration.md` |
-| "How do I wire / connect / integrate this"                                                    | Read and present `{{SKILL_DIR}}/embedded-flow/wire-integration.md`                                                                                                                                                                                      |
-| "Run my app / verify the flow works / check the integration"                                  | Read and execute `{{SKILL_DIR}}/embedded-flow/run-and-verify-integration.md`                                                                                                                                                                            |
-| "My design system changed / regenerate / update pega-components"                              | Re-run analysis (overwrite existing profile) → re-run generation for previously generated components                                                                                                                                                    |
-| Component list provided without explicit flow request                                         | Assume "Generate components" flow; check for Design Profile existence                                                                                                                                                                                   |
+| Request shape                                                                                 | Action                                                                                                                                                                                                                                                                      |
+| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "Analyze my app / scan my codebase / create a design profile"                                 | Read and execute `{{SKILL_DIR}}/embedded-flow/analyze-customer-repo{{SKILL_EXT}}`                                                                                                                                                                                           |
+| "Generate these Pega components for my app" (component list provided, Design Profile exists)  | Read and execute `{{PROMPT_DIR}}/generate-embedded-components{{PROMPT_EXT}}`                                                                                                                                                                                                |
+| "Generate these Pega components for my app" (component list provided, NO Design Profile)      | Execute analysis first → then generation                                                                                                                                                                                                                                    |
+| "Embed [case type] in my app" / "Full embedded flow" / "Integrate pega sdk" / "open workflow" | Execute Step 0 (resolve the case type and components) → analysis → Step 0 of `{{SKILL_DIR}}/embedded-flow/wire-integration{{SKILL_EXT}}` → generation → the remaining wiring steps → verification per `{{SKILL_DIR}}/embedded-flow/run-and-verify-integration{{SKILL_EXT}}` |
+| "How do I wire / connect / integrate this"                                                    | Read and present `{{SKILL_DIR}}/embedded-flow/wire-integration{{SKILL_EXT}}`                                                                                                                                                                                                |
+| "Run my app / verify the flow works / check the integration"                                  | Read and execute `{{SKILL_DIR}}/embedded-flow/run-and-verify-integration{{SKILL_EXT}}`                                                                                                                                                                                      |
+| "My design system changed / regenerate / update the generated Pega components"                | Re-run analysis (overwrite existing profile) → re-run generation for previously generated components                                                                                                                                                                        |
+| Component list provided without explicit flow request                                         | Assume "Generate components" flow; check for Design Profile existence                                                                                                                                                                                                       |
+
+Plain requests route the same way: "learn how my app looks" is analysis; "add the [name] form to my app" or "show the Pega form inside my page" is the full embedded flow; "connect the form to my app" is wiring; "check the form works" is verification; "my app's look changed, update the form" is update/regenerate. When a plain request could fit more than one row, ask the user in plain words which they mean. The phrases here are examples only — for wording that matches none of them, follow "Understand what the user means" in the "Talking to the User" section of the project's global instructions.
 
 ## Step 0 — Discover and resolve (MANDATORY GATE)
 
@@ -55,11 +57,11 @@ Determine which workflow governs the request, then execute it by reading the ref
 
 ### Step 0.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, browser-served `sdk-config.json`, and environment files, then asks once for every missing non-secret value. The user may provide those values in chat or write them into any allowed configuration file named by the gate; the assistant re-reads the files and synchronizes every applicable destination. The gate 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, browser-served `sdk-config.json`, and environment files, then asks once for every missing non-secret value. The user may provide those values in chat or write them into any allowed configuration file named by the gate; the assistant re-reads the files and synchronizes every applicable destination. The gate 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.
 
 ### Step 0.1 — Check for a case type in the prompt
 
-Scan the user's message for a **Pega case type class name** (hyphen-separated segments like `DIXL-MediaCo-Work-NewService`). Note whether one was found — it will be needed in Step 0.2.
+Scan the user's message for a **Pega case type class name** (hyphen-separated segments like `DIXL-MediaCo-Work-NewService`). Note whether one was found — it will be needed in Step 0.2. If there is no class name, also note any **plain case name** the user used instead (e.g. "service request", "new service form") — Step 0.2 matches it against the names the server returns.
 
 ### Step 0.2 — Resolve the case type
 
@@ -69,10 +71,18 @@ 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 a hardcoded component list.
 
+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.
 
 1. Check `applicationIsConstellationCompatible` in the response. If it is `false`, stop and tell the user the application is not Constellation-compatible and cannot be embedded.
-2. If the user's message did NOT contain a case type class name, present the returned case types as a numbered pick-list of `name — ID` pairs and ask which one to embed.
+2. If the user's message did NOT contain a case type class name, present the returned case types as a numbered pick-list of `name — ID` pairs and ask which one to embed. Lead each entry with the name the user will recognise; the ID stays beside it so the choice is unambiguous. If the user gave a **plain case name** instead, first match it case-insensitively against the returned names (whole or partial words; ignore "form" and "case"):
+   - **Exactly one match** — confirm it in plain words with its ID beside it, e.g. "I found **New Service** (`DIXL-MediaCo-Work-NewService`). Shall I use this one?"
+   - **Several matches** — show only those as the pick-list.
+   - **No word match** — compare what the user described with what each returned name suggests (for example "the sign-up one" and **New Service**). If one is a likely fit, offer it as your best guess with its ID beside it and ask for a yes. Otherwise say so plainly ("I couldn't find a case called 'service request'") and show the full pick-list.
+
+   Never proceed on a plain-name match without the user's confirmation.
+
 3. If the user's message DID contain 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 class name.
 4. Write the confirmed `ID` into `sdk-config.json` field `serverConfig.appMashupCaseType`.
 5. **Resolve the starting fields for the confirmed case type**, using the capability that reports what a case type accepts at creation — a different capability from the one that executes data sources, and one the server may not expose. Attempt it directly, the same way. Scope it to the confirmed case type **ID** — the fully qualified class name, not the display label. Record the property names it returns — the wiring step needs them, and they are the only names it is permitted to send. If the capability is unavailable, or it returns nothing, record that no names were confirmed and carry on; the two cases are reported differently but lead to the same result, and neither is a reason to stop. Do not infer property names from anywhere else.
@@ -90,7 +100,7 @@ Reduce that response to a generatable list by applying the following in order. P
 2. **Keep components that appear in at least one lifecycle view.** A view is out-of-the-box, and therefore not part of the case lifecycle, when its name begins with `py` or `pz`, or when it is `CaseHistory`. Keep a component if it appears in **at least one** view that is not out-of-the-box. A component may legitimately appear in both kinds of view — one lifecycle view is enough to keep it. Drop a component only when every view it appears in is out-of-the-box.
 
 3. **Strip what is never generated, wherever it appears.** This rule is independent of point 2 and applies even to components that passed it:
-   - Structural wrappers the SDK's registry already provides and that render nothing of their own: View, Region, FlowContainer, Assignment, CaseView, RootContainer. Templates traverse through these to reach their children rather than rendering them, so there is no visual contract to implement.
+   - Structural wrappers the SDK's registry already provides and that render nothing of their own: View, Region, FlowContainer, Assignment, CaseView, RootContainer, and reference nodes. Templates traverse through these to reach their children rather than rendering them, so there is no visual contract to implement. A reference node resolves a view by name — including the one an embedded record uses for its inline form — and the runtime already handles it.
    - Any component whose name starts with `px` (internal Pega infrastructure)
    - Chrome the SDK adapter provides and that is never generated: NavBar, DeferLoad, VerticalTabs, DashboardFilter
    - Chrome whose fate point 4 decides rather than the data page: ActionButtons, Stages, MultiStep
@@ -98,27 +108,54 @@ Reduce that response to a generatable list by applying the following in order. P
 4. **Add back the chrome the view metadata never returns.** These are decided here rather than by the data page:
 
    - **`FieldValueList`** — whenever the resolved list contains any field component. Every field renders its display-only mode through it, so a case with fields will not render correctly without it.
-   - **`ActionButtons`** — always. Every embedded assignment renders action controls, but they are assignment chrome rather than view content, so they never appear in view metadata. Left ungenerated, the submit and cancel controls render in the SDK's styling in the middle of the customer's form — the most visible mismatch an embedded flow can have. Generate it into `infra/`.
-   - **`MultiStep`** — only when the case has more than one step. It renders the step navigation inside the assignment, so it is also assignment chrome. Generate it into `infra/`.
+   - **`ActionButtons`** — always. Every embedded assignment renders action controls, but they are assignment chrome rather than view content, so they never appear in view metadata. Left ungenerated, the submit and cancel controls render in the SDK's styling in the middle of the customer's form — the most visible mismatch an embedded flow can have.
+   - **`MultiStep`** — only when the case has more than one step. It renders the step navigation inside the assignment, so it is also assignment chrome.
+   - **`AlertBanner`** — always. The assignment shows server validation errors and page messages through it. Left ungenerated, those messages do not appear at all.
+   - **`AssignmentHeader`** — always. The SDK draws the current step's title above the form through it. Left ungenerated, the title renders in the SDK's styling.
+   - **`Toast`** — always. The SDK shows short failure messages after an action — such as a failed save or cancel — through it. Left ungenerated, they render in the SDK's styling.
+
+   `AlertBanner`, `AssignmentHeader`, and `Toast` are the three newly added design system extensions. Generate them like other design system extensions. `FieldValueList` is also a design system extension and follows the same rule. Every component, chrome included, is generated directly in the generated components folder — there are no type subfolders.
 
    `Stages` is the counter-example: it is case chrome, never appears in an embedded assignment, and must not be generated for an embedded flow. It stays stripped.
 
-5. **Present the resolved list, and the exclusions with their reasons.** Name what will be generated, then separately name what was dropped because it appears only in out-of-the-box views, and what was stripped because it is never generated. An exclusion the user disagrees with is far easier to catch when it is visible, and a silently missing component surfaces much later as a rendering gap. **Report the starting fields here too** — either the property names the case type accepts at creation, or that none were confirmed and pre-fill will therefore be off. This is the last point before analysis and generation begin, so it is the last cheap moment for the user to correct either one. Then ask whether to proceed.
+5. **Present the resolved list, and the exclusions with their reasons.** Name what will be generated, then separately name what was dropped because it appears only in out-of-the-box views, what was stripped because it is never generated, and what was added because a selected component declares it as a registry dependency. An exclusion the user disagrees with is far easier to catch when it is visible, and a silently missing component surfaces much later as a rendering gap. **Report the starting fields here too** — either the property names the case type accepts at creation, or that none were confirmed and pre-fill will therefore be off. This is the last point before analysis and generation begin, so it is the last cheap moment for the user to correct either one. Then ask whether to proceed.
+
+   Write this for someone who does not know Pega's component names: describe each piece by what it shows on screen with its component name in brackets, give each reason for leaving something out in everyday words, and say what a missing starting field means for the user in practice.
+
+6. **Beyond the additions in point 4, generate only what this resolved list contains, plus the registry dependencies the selected components declare.** Do NOT add components based on assumptions about what a case type might need.
 
-6. **Beyond the additions in point 4, generate only what this resolved list contains.** Do NOT add components based on assumptions about what a case type might need.
+   Some components are orchestrators: they render no control of their own, and instead resolve other components from the registry at runtime. Reference fields and embedded data fields are the clearest examples — one of them may resolve a table, a repeating-group template, a picker, or a value display depending on how it was configured. Those dependencies are building blocks rather than fields, so they never appear in view metadata and this data page never returns them. A registry lookup that finds nothing degrades to a fallback or a blank render rather than raising an error, so an orchestrator generated on its own looks like a styling fault rather than a missing component.
+
+   A dependency named in a generated component's own skill file is therefore **not** an assumption — it is part of that component's contract. Read each selected component's skill file, collect the registry keys it declares it will resolve, and add any that are neither already registered in the project nor already in the list. The dependency is **transitive**: a dependency's own skill may declare further ones, so repeat until the set stops growing. Record which component required each addition, and report them under point 5 separately from the chrome added by point 4.
+
+   The distinction to hold: a dependency a skill file declares is required, and omitting it produces a component that cannot render. A component you believe a case type might need is not. Never widen the list on your own judgement.
 
 ### Step 0.4 — Proceed to workflows
 
 With the case type and the component list confirmed, proceed in this order:
 
 1. Analyze the customer's codebase (if no Design Profile exists)
-2. Execute **Step 0 of `{{SKILL_DIR}}/embedded-flow/wire-integration.md`** — resolve the launch point and the render target
+2. Execute **Step 0 of `{{SKILL_DIR}}/embedded-flow/wire-integration{{SKILL_EXT}}`** — resolve the launch point and the render target
 3. Generate only the confirmed components
 4. Wire the integration — the remaining steps of the wiring skill
-5. Verify at runtime per `{{SKILL_DIR}}/embedded-flow/run-and-verify-integration.md`
+5. Verify at runtime per `{{SKILL_DIR}}/embedded-flow/run-and-verify-integration{{SKILL_EXT}}`
 
 Item 2 sits after analysis because resolving the render target may require asking the user, and the options must be drawn from surfaces the application already has — which is what the Design Profile records. It sits before generation because it is the only step that can cancel the flow, and generation writes a folder of components.
 
+## Progress milestones
+
+Announce these to the user as you reach them, in plain words and with a counter — "Step 5 of 7 — Building the form pieces". When the user asks for only part of the flow, count only the milestones that part covers. The skills and prompts you run inside a milestone do not start a counter of their own.
+
+| #   | Say to the user                | Covers                                                                                                                                                                                                           |
+| --- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Connecting to your Pega server | Step 0.0                                                                                                                                                                                                         |
+| 2   | Finding what the form needs    | Steps 0.1 to 0.3                                                                                                                                                                                                 |
+| 3   | Learning your app's look       | Codebase analysis                                                                                                                                                                                                |
+| 4   | Choosing where the form opens  | Step 0 of the wire-integration skill                                                                                                                                                                             |
+| 5   | Building the form pieces       | Component generation — after each one, say what is ready and count it: "Date picker field ready (4 of 12)"                                                                                                       |
+| 6   | Connecting it to your app      | The remaining wire-integration steps                                                                                                                                                                             |
+| 7   | Trying it out                  | The run-and-verify-integration skill, announcing its parts as that skill describes. Complete only once its Stage 4 has run — if it stopped earlier, never present step 7 as done; say "not verified yet" instead |
+
 ## Launch point and render target — required before anything is written
 
 Wiring and the full embedded flow need two things the user often states in passing: the control that launches the case ("on click of the apply loan button") and the surface it renders on ("in a modal", "as a new page"). Capture whatever they said verbatim; do not resolve either to a file yet.
@@ -133,7 +170,7 @@ If the user named a launch point but no render target, the skill infers it from
 | Generate           | Case type class + component list + Design Profile (or permission to create one)                                             |
 | Full embedded flow | Case type class + server-resolved component list + codebase access + launch point + render target                           |
 | Wire integration   | Case type class + generated components folder (location resolved during analysis) must exist + launch point + render target |
-| Verify integration | A wired integration + a human available to authenticate when the flow reaches the Pega login form                           |
+| Verify integration | A wired integration + the user in the conversation to sign in when the login window you open asks for it                    |
 
 ---
 
@@ -146,11 +183,12 @@ If the user named a launch point but no render target, the skill infers it from
 5. **Never modify the customer's existing code** except at the seams that the wiring and verification skills enumerate. The generated components folder (location resolved during analysis and recorded in the Design Profile) is purely additive, and a failing verification check is never permission to edit customer code outside those seams to make it pass.
 6. **Component skills are authoritative** — the behavioral contracts in `{{SKILL_DIR}}/field-skills/`, `template-skills/`, `widget-skills/`, `design-system-extension-skills/`, and `infra-skills/` define what each component must do. These are non-negotiable.
 7. **Adapt to the customer's framework** — the skills and prompts are framework-agnostic. Determine the customer's framework from their project configuration and apply conventions accordingly.
-8. **Verification is mandatory, and it is not only static** — the generation prompt's checks confirm the generated files are well-formed. They do not confirm the flow runs. Whenever the integration has been wired, finish with `{{SKILL_DIR}}/embedded-flow/run-and-verify-integration.md` and report how far it got. Never declare success on static checks alone.
+8. **Verification is mandatory, and it is not only static** — the generation prompt's checks confirm the generated files are well-formed. They do not confirm the flow runs. Whenever the integration has been wired, go straight on to `{{SKILL_DIR}}/embedded-flow/run-and-verify-integration{{SKILL_EXT}}` without asking first, run every stage yourself, and repair what fails. Re-read that skill in full before starting, however long the run has been. Report how far it got only when it stopped for one of the reasons in that skill's "Stopping early" section, and then say plainly that the integration is not verified yet. Never declare success on static checks alone, and never replace a stage with a lighter check because the run is long or large.
 9. **Case type class must be used** — the confirmed case type class must be written into `sdk-config.json` (in the `appMashupCaseType` field) and used in the bootstrap/wiring module when calling the mashup API to create a case.
-10. **Only generate server-resolved components** — generate exactly what Step 0.3 produced: the components the case type's data page returned and that survived its filters, plus the additions point 4 names (`FieldValueList`, `ActionButtons`, and `MultiStep` for a multi-step case). Do NOT add anything else based on assumptions about what a case type might need.
+10. **Only generate server-resolved components, their declared dependencies, and the named chrome** — generate exactly what Step 0.3 produced: the components the case type's data page returned and that survived its filters, the additions point 4 names (`FieldValueList`, `ActionButtons`, `AlertBanner`, `AssignmentHeader`, `Toast`, and `MultiStep` for a multi-step case), and the registry dependencies that the selected components' own skill files declare, resolved transitively per point 6. Do NOT add anything else based on assumptions about what a case type might need.
 11. **Never silently replace existing behaviour, and never assume where the flow renders** — before anything is written, resolve the launch point and the render target. If the named control already does something, ask whether to override; if they decline, stop the whole flow, do not embed on a different control, and do not leave partial edits behind. If the render target was never stated and cannot be inherited from the control's existing behaviour, ask. See Step 0 of the wire-integration skill.
 12. **Never handle credentials** — when verification reaches the Pega login form in the browser, a human signs in at a visible window. Do not request, capture, log, echo, or store those credentials, at any stage and under any failure condition.
+13. **Talk to the user in plain language** — follow the "Talking to the User" section of the project's global instructions for every progress update, question, and problem, and announce the milestones in [Progress milestones](#progress-milestones) with a counter. Ask every question through your AI tool's question feature, as that section describes. The internal names in these instructions are for your own work and stay exactly as written.
 
 ## Error handling
 
@@ -164,6 +202,7 @@ If the user named a launch point but no render target, the skill infers it from
 | Every component is removed by the lifecycle filter               | The case type may have no lifecycle views. Show the views that were returned, explain that all of them are out-of-the-box, and ask the user to confirm before proceeding                                                                                                                                                                       |
 | Customer's project uses an unfamiliar framework                  | Read the framework's documentation (if accessible) + rely heavily on the representative components from the Design Profile                                                                                                                                                                                                                     |
 | A requested component has no skill file                          | The name is not a Pega component name. Resolve it to a canonical one using the staged process in Step 1 of the generation prompt (normalized name, then alias table, then behaviour class, then ask the user), implement that component's skill, and tell the user which substitution you made                                                 |
+| A generated component renders blank or shows the fallback        | Most likely a registry dependency it resolves at runtime was never generated. Orchestrator components fail this way silently. Re-read that component's skill file, collect the registry keys it declares, and confirm each one is registered — see point 6 of Step 0.3. Do not treat it as a styling fault                                     |
 | Design Profile extraction finds no clear patterns                | Ask the user to point to specific example components in their codebase                                                                                                                                                                                                                                                                         |
 | Generated component fails type check after 2 retries             | Report the specific error, show the problematic code, and ask the user for guidance                                                                                                                                                                                                                                                            |
 | Customer uses multiple design systems in one project             | Ask which one should be used for the Pega components, or default to the one used for form elements                                                                                                                                                                                                                                             |
@@ -173,3 +212,5 @@ If the user named a launch point but no render target, the skill infers it from
 | Pega server unreachable during runtime verification              | Report that verification is limited to the static gates, name the host that could not be reached, and do not present it as an integration failure                                                                                                                                                                                              |
 | Verification fails on customer code outside the seams            | Report the file, symptom and likely cause, and stop. Do not edit the customer's application to make the check pass                                                                                                                                                                                                                             |
 | No case type class provided and discovery is unavailable         | Stop and report why. Do not ask the user to supply a component list from memory, and do not guess.                                                                                                                                                                                                                                             |
+
+Word every message in this table for the user in plain language — what happened, what it affects, and what they can do next — while keeping any value they must act on exact.