@pega/sdk 0.0.6 → 0.0.8

package/dist/index.js

@@ -547,7 +547,7 @@ async function scaffold(choices, targetDir, onProgress) {
         }
       }
     }
-    generateAiConfigs(targetDir, aiTool);
+    generateAiConfigs(targetDir, choices);
   }
   report("Finalizing project configuration\u2026");
   selectReactPackageManifest(targetDir, framework, includeTemplates, componentCategories);
@@ -791,6 +791,7 @@ function cursorSkillDescription(relPath) {
     if (subdir === "template-skills") return `Template component skill: ${name}`;
     if (subdir === "widget-skills") return `Widget component skill: ${name}`;
     if (subdir === "design-system-extension-skills") return `DSE component skill: ${name}`;
+    if (subdir === "infra-skills") return `Infra component skill: ${name}`;
   }
   return relPath.replace(/\.md$/, "").split("/").pop();
 }
@@ -1013,10 +1014,26 @@ function applyPlannedFiles(files, policy, options = {}) {
   }
   return counts;
 }
-function generateAiConfigs(targetDir, aiTool) {
+function generateAiConfigs(targetDir, choices) {
   const aiCommonDir = path2.join(targetDir, ".ai-common");
   if (!fs2.existsSync(aiCommonDir)) return;
-  applyPlannedFiles(planAiConfigs(aiCommonDir, targetDir, aiTool), "override", { markers: false });
+  if (choices.aiTool) {
+    applyPlannedFiles(planAiConfigs(aiCommonDir, targetDir, choices.aiTool), "override", { markers: false });
+  }
+  if (choices.aiTool && choices.serverUrl && choices.appAlias && choices.clientId) {
+    const { config: mcpConfig, destRelPath: mcpDestRelPath } = resolveMcpConfig(aiCommonDir, {
+      aiTool: choices.aiTool,
+      serverUrl: choices.serverUrl,
+      appAlias: choices.appAlias,
+      clientId: choices.clientId,
+      mcpRuleName: choices.mcpRuleName,
+      mcpRuleInsKey: choices.mcpRuleInsKey
+    });
+    writeManagedJson(path2.join(targetDir, mcpDestRelPath), mcpConfig, "override", MCP_CONFIG_USER_KEYS);
+    if (choices.aiTool === "cursor") {
+      ensureGitignoreEntry(targetDir, mcpDestRelPath);
+    }
+  }
   fs2.rmSync(aiCommonDir, { recursive: true });
 }
 var EMBEDDED_GLOBAL_FILE = "ai-agent-instructions-embedded.md";
@@ -1036,6 +1053,35 @@ var SDK_CONFIG_USER_KEYS = [
   "authConfig.mashupUserIdentifier",
   "authConfig.portalClientId"
 ];
+var MCP_CONFIG_USER_KEYS = ["url", "clientId"];
+var MCP_CONFIG_FILES = {
+  copilot: { source: "copilot.mcp.json", dest: path2.join(".vscode", "mcp.json") },
+  cursor: { source: "cursor.mcp.json", dest: path2.join(".cursor", "mcp.json") },
+  "claude-code": { source: "claude-code.mcp.json", dest: ".mcp.json" }
+};
+function resolveMcpConfig(aiCommonSrc, choices) {
+  const { source, dest } = MCP_CONFIG_FILES[choices.aiTool];
+  const srcPath = path2.join(aiCommonSrc, "mcp", source);
+  if (!fs2.existsSync(srcPath)) {
+    throw new Error(`MCP config template not found at ${srcPath}. Ensure the template source is available.`);
+  }
+  const tokens = {
+    "{InfinityURL}": choices.serverUrl,
+    "{AppAlias}": choices.appAlias,
+    "{ClientId}": choices.clientId
+  };
+  if (choices.mcpRuleName) tokens["{MCPRuleName}"] = choices.mcpRuleName;
+  if (choices.mcpRuleInsKey) tokens["{MCPRuleInsKey}"] = choices.mcpRuleInsKey;
+  const content = applyTokens(fs2.readFileSync(srcPath, "utf-8"), tokens);
+  return { config: JSON.parse(content), destRelPath: dest };
+}
+function ensureGitignoreEntry(targetDir, entry) {
+  const gitignorePath = path2.join(targetDir, ".gitignore");
+  const existing = fs2.existsSync(gitignorePath) ? fs2.readFileSync(gitignorePath, "utf-8") : "";
+  if (existing.split(/\r?\n/).some((line) => line.trim() === entry)) return;
+  const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+  fs2.writeFileSync(gitignorePath, existing + separator + entry + "\n");
+}
 function buildSdkConfig(choices) {
   return {
     serverConfig: {
@@ -1079,6 +1125,11 @@ function collectEmbeddedConflicts(targetDir, choices) {
   if (isConflict(sdkConfigPath, buildSdkConfig(choices), SDK_CONFIG_USER_KEYS)) {
     conflicts.push(sdkConfigPath);
   }
+  const { config: mcpConfig, destRelPath: mcpDestRelPath } = resolveMcpConfig(aiCommonSrc, choices);
+  const mcpConfigPath = path2.join(targetDir, mcpDestRelPath);
+  if (isConflict(mcpConfigPath, mcpConfig, MCP_CONFIG_USER_KEYS)) {
+    conflicts.push(mcpConfigPath);
+  }
   return conflicts.map((filePath) => path2.relative(targetDir, filePath));
 }
 async function scaffoldEmbedded(choices, targetDir, onProgress) {
@@ -1129,6 +1180,12 @@ async function scaffoldEmbedded(choices, targetDir, onProgress) {
   if (staticDir !== targetDir && fs2.existsSync(path2.join(targetDir, "sdk-config.json"))) {
     report(`\u26A0\uFE0F  A sdk-config.json also exists at the project root. The active one is ${sdkConfigPath}.`);
   }
+  report("Creating MCP server configuration\u2026");
+  const { config: mcpConfig, destRelPath: mcpDestRelPath } = resolveMcpConfig(aiCommonSrc, choices);
+  writeManagedJson(path2.join(targetDir, mcpDestRelPath), mcpConfig, policy, MCP_CONFIG_USER_KEYS);
+  if (aiTool === "cursor") {
+    ensureGitignoreEntry(targetDir, mcpDestRelPath);
+  }
   report("Installing dependencies (this may take a minute)\u2026");
   let installSucceeded = true;
   try {
@@ -1247,7 +1304,7 @@ Usage: ${pc.cyan("npx @pega/sdk init")}`);
       process.exit(0);
     }
     p.log.info(pc.dim("\nNow let's connect to your Pega server."));
-    const serverUrl = await p.text({
+    const serverUrlResult = await p.text({
       message: "What is your Pega server URL?",
       placeholder: "https://your-pega-server.com/prweb",
       validate(value) {
@@ -1255,29 +1312,30 @@ Usage: ${pc.cyan("npx @pega/sdk init")}`);
         if (!value.startsWith("http")) return "Must be a valid URL starting with http:// or https://";
       }
     });
-    if (p.isCancel(serverUrl)) {
+    if (p.isCancel(serverUrlResult)) {
       p.cancel("Operation cancelled.");
       process.exit(0);
     }
-    const appAlias = await p.text({
+    const serverUrl2 = serverUrlResult.replace(/\/+$/, "");
+    const appAlias2 = await p.text({
       message: "What is your Pega application alias?",
       placeholder: "MyApp",
       validate(value) {
         if (!value) return "Application alias is required.";
       }
     });
-    if (p.isCancel(appAlias)) {
+    if (p.isCancel(appAlias2)) {
       p.cancel("Operation cancelled.");
       process.exit(0);
     }
-    const clientId = await p.text({
+    const clientId2 = await p.text({
       message: "What is the OAuth Client ID for your app?",
       placeholder: "Your OAuth 2.0 client identifier",
       validate(value) {
         if (!value) return "Client ID is required for authentication.";
       }
     });
-    if (p.isCancel(clientId)) {
+    if (p.isCancel(clientId2)) {
       p.cancel("Operation cancelled.");
       process.exit(0);
     }
@@ -1292,16 +1350,37 @@ Usage: ${pc.cyan("npx @pega/sdk init")}`);
       p.cancel("Operation cancelled.");
       process.exit(0);
     }
+    p.log.info(pc.dim("\nIf you've configured an MCP server for this app, we can wire it up too (optional)."));
+    const mcpRuleNameResult = await p.text({
+      message: "What is your Pega MCP rule name? (press Enter to skip)",
+      placeholder: "SDKMCP"
+    });
+    if (p.isCancel(mcpRuleNameResult)) {
+      p.cancel("Operation cancelled.");
+      process.exit(0);
+    }
+    const mcpRuleInsKeyResult = await p.text({
+      message: "What is your Pega MCP rule instance key? (press Enter to skip)",
+      placeholder: "@baseclass!SDKMCP"
+    });
+    if (p.isCancel(mcpRuleInsKeyResult)) {
+      p.cancel("Operation cancelled.");
+      process.exit(0);
+    }
+    const mcpRuleName2 = mcpRuleNameResult || void 0;
+    const mcpRuleInsKey2 = mcpRuleInsKeyResult || void 0;
     const embeddedTargetDir = cwd;
     p.note(
       [
         `${pc.bold("Mode")}:          Embed Pega flow`,
         `${pc.bold("Directory")}:     ${embeddedTargetDir}`,
         `${pc.bold("AI Tool")}:       ${embeddedAiTool}`,
-        `${pc.bold("Server")}:        ${serverUrl}`,
-        `${pc.bold("App Alias")}:     ${appAlias}`,
-        `${pc.bold("Client ID")}:     ${clientId}`,
-        `${pc.bold("Operator")}:      ${userIdentifier}`
+        `${pc.bold("Server")}:        ${serverUrl2}`,
+        `${pc.bold("App Alias")}:     ${appAlias2}`,
+        `${pc.bold("Client ID")}:     ${clientId2}`,
+        `${pc.bold("Operator")}:      ${userIdentifier}`,
+        `${pc.bold("MCP Rule")}:      ${mcpRuleName2 ?? pc.dim("(not configured \u2014 markers left in generated file)")}`,
+        `${pc.bold("MCP Ins Key")}:   ${mcpRuleInsKey2 ?? pc.dim("(not configured \u2014 markers left in generated file)")}`
       ].join("\n"),
       "Configuration"
     );
@@ -1315,10 +1394,12 @@ Usage: ${pc.cyan("npx @pega/sdk init")}`);
     }
     const embeddedChoices = {
       aiTool: embeddedAiTool,
-      serverUrl,
-      appAlias,
-      clientId,
-      userIdentifier
+      serverUrl: serverUrl2,
+      appAlias: appAlias2,
+      clientId: clientId2,
+      userIdentifier,
+      mcpRuleName: mcpRuleName2,
+      mcpRuleInsKey: mcpRuleInsKey2
     };
     let conflicts = [];
     try {
@@ -1407,6 +1488,11 @@ Usage: ${pc.cyan("npx @pega/sdk init")}`);
     process.exit(0);
   }
   let aiTool = null;
+  let serverUrl;
+  let appAlias;
+  let clientId;
+  let mcpRuleName;
+  let mcpRuleInsKey;
   if (aiIntegration) {
     const aiToolResult = await p.select({
       message: "Which AI coding tool will you use?",
@@ -1433,6 +1519,62 @@ Usage: ${pc.cyan("npx @pega/sdk init")}`);
       process.exit(0);
     }
     aiTool = aiToolResult;
+    p.log.info(pc.dim("\nIf you'd like the new project to include an MCP config, we need a few connection details."));
+    const serverUrlResult = await p.text({
+      message: "What is your Pega server URL?",
+      placeholder: "https://your-pega-server.com/prweb",
+      validate(value) {
+        if (!value) return "Server URL is required.";
+        if (!value.startsWith("http")) return "Must be a valid URL starting with http:// or https://";
+      }
+    });
+    if (p.isCancel(serverUrlResult)) {
+      p.cancel("Operation cancelled.");
+      process.exit(0);
+    }
+    const appAliasResult = await p.text({
+      message: "What is your Pega application alias?",
+      placeholder: "MyApp",
+      validate(value) {
+        if (!value) return "Application alias is required.";
+      }
+    });
+    if (p.isCancel(appAliasResult)) {
+      p.cancel("Operation cancelled.");
+      process.exit(0);
+    }
+    const clientIdResult = await p.text({
+      message: "What is the OAuth Client ID for your app?",
+      placeholder: "Your OAuth 2.0 client identifier",
+      validate(value) {
+        if (!value) return "Client ID is required for authentication.";
+      }
+    });
+    if (p.isCancel(clientIdResult)) {
+      p.cancel("Operation cancelled.");
+      process.exit(0);
+    }
+    const mcpRuleNameResult = await p.text({
+      message: "What is your Pega MCP rule name? (press Enter to skip)",
+      placeholder: "SDKMCP"
+    });
+    if (p.isCancel(mcpRuleNameResult)) {
+      p.cancel("Operation cancelled.");
+      process.exit(0);
+    }
+    const mcpRuleInsKeyResult = await p.text({
+      message: "What is your Pega MCP rule instance key? (press Enter to skip)",
+      placeholder: "@baseclass!SDKMCP"
+    });
+    if (p.isCancel(mcpRuleInsKeyResult)) {
+      p.cancel("Operation cancelled.");
+      process.exit(0);
+    }
+    serverUrl = String(serverUrlResult).replace(/\/+$/, "");
+    appAlias = String(appAliasResult);
+    clientId = String(clientIdResult);
+    mcpRuleName = String(mcpRuleNameResult) || void 0;
+    mcpRuleInsKey = String(mcpRuleInsKeyResult) || void 0;
   }
   const framework = await p.select({
     message: "Select a UI framework for your Pega SDK project:",
@@ -1541,7 +1683,12 @@ Usage: ${pc.cyan("npx @pega/sdk init")}`);
     framework,
     aiTool,
     includeTemplates,
-    componentCategories
+    componentCategories,
+    serverUrl,
+    appAlias,
+    clientId,
+    mcpRuleName,
+    mcpRuleInsKey
   };
   const spinner2 = p.spinner();
   spinner2.start("Scaffolding your project\u2026");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pega/sdk",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Scaffold a Pega SDK application project",
   "type": "module",
   "bin": {

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

@@ -10,9 +10,10 @@ migrating the design system of components that already exist. You execute these
 written, rather than improvising your own approach.
 
 This repo is a reference implementation customers clone and re-skin: the UI components (fields, templates, widgets,
-and design system extensions) are meant to be replaced with any design system, while the SDK wiring (component map
-registry mechanics, infrastructure components, event handling helpers, the SDK bridge package, and the application
-bootstrap/auth logic) is reusable infrastructure you must never break.
+design system extensions, and the three overridable infrastructure chrome components) are meant to be replaced with
+any design system, while the SDK wiring (component map registry mechanics, the SDK-provided infrastructure
+components, event handling helpers, the SDK bridge package, and the application bootstrap/auth logic) is reusable
+infrastructure you must never break.
 
 ## Startup behavior
 
@@ -27,6 +28,7 @@ The **first time you respond in a conversation**, before doing any routing or fi
   2. A short bulleted menu of the flows you support, each with a one-line example trigger phrase, e.g.:
      - **Add/replace a single component** — "add a Dropdown field using Chakra UI"
      - **Batch-generate one type** — "generate all widget components with Ant Design"
+     - **Generate infrastructure chrome** — "generate infra components with Carbon"
      - **Generate everything** — "generate all components using Radix"
      - **Identify components from a screenshot** — attach an image and ask "what components are in this screenshot"
      - **Migrate the design system** — "replace all field components with Carbon" or "migrate the whole app to Chakra UI"
@@ -35,10 +37,14 @@ The **first time you respond in a conversation**, before doing any routing or fi
      - **Flow**: options = Add/replace a single component | Batch-generate one type | Generate everything |
        Identify components from a screenshot | Migrate the design system.
      - **Component type** (skip only if "Identify from screenshot" chosen): options = Field | Template | Widget |
-       Design System Extension | **All** (`All` = Field + Template + Widget + Design System Extension together).
+       Design System Extension | Infra (chrome) | **All** (`All` = Field + Template + Widget + Design System
+       Extension + Infra together).
        Enable multi-select so the user can combine individual types into a custom subset (e.g. Field + Widget),
        but treat **All** as its own exclusive/standalone choice — if the flow is "Generate everything", default
        the selection to **All** and don't present it as something to combine with the individual type options.
+       For the "Generate everything" flow, **All** means every type is eligible — not that every component gets
+       generated. The concrete list comes from the portal the user picks inside
+       `generate-all-components{{PROMPT_EXT}}`, so don't ask for component names here.
      - **Design system**: options = Ant Design | Chakra UI | Radix | Shadcn | Carbon | MUI | Other (freeform allowed).
        Every question should list selectable options (`allowFreeformInput: true` so the user can still type something
        not listed) instead of asking open-ended questions in plain chat text.
@@ -53,16 +59,17 @@ before writing any code**. Never paraphrase or execute steps from memory — alw
 skill file it tells you to read) at the start of the task, and follow every numbered step in order without
 skipping or shortcutting any of them.
 
-| Request shape                                                                                                                                       | Prompt file to read and follow                                                                                                                                                                              |
-| --------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| One new/replacement component, one type (e.g. "add an AutoComplete field with Chakra UI")                                                           | `{{PROMPT_DIR}}/add-component{{PROMPT_EXT}}`                                                                                                                                                                |
-| Multiple/all field components, one design system                                                                                                    | `{{PROMPT_DIR}}/generate-field-components{{PROMPT_EXT}}`                                                                                                                                                    |
-| Multiple/all template components, one design system                                                                                                 | `{{PROMPT_DIR}}/generate-template-components{{PROMPT_EXT}}`                                                                                                                                                 |
-| Multiple/all widget components, one design system                                                                                                   | `{{PROMPT_DIR}}/generate-widget-components{{PROMPT_EXT}}`                                                                                                                                                   |
-| Multiple/all design system extension components, one design system                                                                                  | `{{PROMPT_DIR}}/generate-dse-components{{PROMPT_EXT}}`                                                                                                                                                      |
-| Multiple component types at once, or "generate all components"                                                                                      | `{{PROMPT_DIR}}/generate-all-components{{PROMPT_EXT}}` (wave-based orchestration — launch subagents via `runSubagent`, respecting the ≤10-subagents-per-wave limit defined in that prompt)                  |
-| A screenshot/image is attached and the user wants to know what components are in it (no migration requested)                                        | `{{PROMPT_DIR}}/identify-components{{PROMPT_EXT}}` — output only the single `components="..."` line it specifies                                                                                            |
-| Migrating/replacing the design system of components that **already exist** — full app, or scoped by folder/named-shorthand/explicit list/screenshot | `{{PROMPT_DIR}}/replace-design-system{{PROMPT_EXT}}` (reads `{{PROMPT_DIR}}/component-manifest.json` for scope resolution; targeted migration for ≤10 resolved components, full 9-wave migration otherwise) |
+| Request shape                                                                                                                                       | Prompt file to read and follow                                                                                                                                                                                                                                                                                                                    |
+| --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| One new/replacement component, one type (e.g. "add an AutoComplete field with Chakra UI")                                                           | `{{PROMPT_DIR}}/add-component{{PROMPT_EXT}}`                                                                                                                                                                                                                                                                                                      |
+| Multiple/all field components, one design system                                                                                                    | `{{PROMPT_DIR}}/generate-field-components{{PROMPT_EXT}}`                                                                                                                                                                                                                                                                                          |
+| Multiple/all template components, one design system                                                                                                 | `{{PROMPT_DIR}}/generate-template-components{{PROMPT_EXT}}`                                                                                                                                                                                                                                                                                       |
+| Multiple/all widget components, one design system                                                                                                   | `{{PROMPT_DIR}}/generate-widget-components{{PROMPT_EXT}}`                                                                                                                                                                                                                                                                                         |
+| Multiple/all design system extension components, one design system                                                                                  | `{{PROMPT_DIR}}/generate-dse-components{{PROMPT_EXT}}`                                                                                                                                                                                                                                                                                            |
+| Multiple/all infrastructure (chrome) components, one design system                                                                                  | `{{PROMPT_DIR}}/generate-infra-components{{PROMPT_EXT}}` (only `ActionButtons`, `Stages`, `MultiStep` — every other infra component is SDK-provided)                                                                                                                                                                                              |
+| Multiple component types at once, or "generate all components"                                                                                      | `{{PROMPT_DIR}}/generate-all-components{{PROMPT_EXT}}` (opens with a mandatory server-driven gate — pick a portal, choose landing pages and/or case types, then pick components — then wave-based orchestration over that selection only: launch subagents via `runSubagent`, respecting the ≤10-subagents-per-wave limit defined in that prompt) |
+| A screenshot/image is attached and the user wants to know what components are in it (no migration requested)                                        | `{{PROMPT_DIR}}/identify-components{{PROMPT_EXT}}` — output only the single `components="..."` line it specifies                                                                                                                                                                                                                                  |
+| Migrating/replacing the design system of components that **already exist** — full app, or scoped by folder/named-shorthand/explicit list/screenshot | `{{PROMPT_DIR}}/replace-design-system{{PROMPT_EXT}}` (reads `{{PROMPT_DIR}}/component-manifest.json` for scope resolution; targeted migration for ≤10 resolved components, full 9-wave migration otherwise)                                                                                                                                       |
 
 If a request mixes generation and migration ambiguously, use `vscode_askQuestions` to ask which they mean (options:
 "Generate/replace" vs "Migrate existing") before picking a prompt — generation prompts assume the component
@@ -74,8 +81,8 @@ change.
 - That prompt tells you to launch per-component subagents using prompts named `replace-field` (fields) and
   `replace-component` (everything else). **These files do not exist in `{{PROMPT_DIR}}/`.** When launching those
   subagents yourself via `runSubagent`, give each one the equivalent instructions inline instead: the relevant
-  general skill (`{{SKILL_DIR}}/field-components.md`, `template-components.md`, `widget-components.md`, or
-  `design-system-extension.md`), the component-specific skill file
+  general skill (`{{SKILL_DIR}}/field-components.md`, `template-components.md`, `widget-components.md`,
+  `design-system-extension.md`, or `infra-components.md`), the component-specific skill file
   (`{{SKILL_DIR}}/{type}-skills/<Name>.md`), the target design system, and the same "preserve visual intent /
   keep default export name / update in place" constraints that `add-component{{PROMPT_EXT}}` uses for a single
   component.
@@ -89,28 +96,41 @@ Every generation prompt requires: component name(s), component type, target desi
 (screenshot, `components=` list, or `scope=` folder/shorthand) — if none are given, it defaults to a full 9-wave
 migration, so confirm that's really what the user wants before proceeding. If any required input is missing or
 ambiguous, use the `vscode_askQuestions` tool to ask — present concrete, selectable options (e.g. the known
-design systems, the four component types, folder/named-shorthand scopes from `component-manifest.json`) rather
+design systems, the five component types, folder/named-shorthand scopes from `component-manifest.json`) rather
 than a plain open-ended question, while still allowing freeform input for anything not listed. Do not guess a
 design system or silently default to MUI.
 
 ## Guardrails
 
-- **One folder per component — never a shared/monolithic file.** Every component (field, template, widget, or
-  designSystemExtension) must be created at `<outputPath>/<ComponentName>/` with a main implementation file plus a
-  sibling barrel/re-export file following the project's established convention — exactly as
+- **In the "generate all components" flow, the generation set is server-resolved.** That prompt's Step 0.5 picks
+  a portal, then landing pages and/or case types within it, then a component list from those — and nothing outside
+  that selection may be generated. Do not widen it with components you expect a portal to need, and do not skip
+  the gate because the user said "everything".
+- **One folder per component — never a shared/monolithic file.** Every component (field, template, widget,
+  designSystemExtension, or infra) must be created at `<outputPath>/<ComponentName>/` with a main implementation file
+  plus a sibling barrel/re-export file following the project's established convention — exactly as
   Step 5/6 of `add-component{{PROMPT_EXT}}` specifies. Never write multiple components into one file, never
   create a catch-all file like `generated/<designSystem>Components`, and never export a single bundled object
   (e.g. `generatedComponents`) that the component map spreads in one line. This applies identically whether you
   generate one component, a batch of one type, or "all components" via `generate-all-components{{PROMPT_EXT}}` — the
   wave/subagent orchestration in that flow does not change the per-component file-and-folder contract.
 - The project's component map file must get one **named import + one map entry per component**, added under the matching
-  category comment (Fields / Templates / Widgets / Design System Extension), never a single spread of a bundled
+  category comment (Fields / Templates / Widgets / Design System Extension / Infra), never a single spread of a bundled
   object.
-- Never modify the auth/bootstrap logic in the application's bootstrap modules, infrastructure components
-  (beyond what a migration prompt explicitly directs), the event handling helper module, or anything in the
+- Never modify the auth/bootstrap logic in the application's bootstrap modules, the SDK-provided infrastructure
+  components (beyond what a migration prompt explicitly directs), the event handling helper module, or anything in the
   SDK bridge package. The one exception: `replace-design-system{{PROMPT_EXT}}` explicitly requires wrapping the
   existing provider tree in the application's bootstrap module with a new design-system provider — that specific,
   additive change is allowed only during a migration flow.
+- **Only three infrastructure components may ever be generated** — `ActionButtons`, `Stages`, and `MultiStep`. Every
+  other infrastructure component (`NavBar`, `DeferLoad`, `VerticalTabs`, `DashboardFilter`, and anything else) is
+  SDK-provided plumbing: skip it and say why. That list never grows.
+- An infra entry in the component map is an **override** of a component the SDK already contributes, so it must be
+  listed **after** the SDK's built-in component spread. Listed before it, the spread wins and the override silently
+  does nothing.
+- Infrastructure components have a fixed runtime contract — inputs, callback signatures, and localization come from
+  the SDK component being replaced. Only markup and styling are yours to change. `ActionButtons` receives plain
+  display props and must not be given a PConnect accessor.
 - Never remove the SDK's built-in component spread in the project's component map file — only add or replace entries.
 - Field components must handle `displayMode` (`DISPLAY_ONLY` / `STACKED_LARGE_VAL`) via the field-value display
   component, obtained through the component registry, never a hardcoded import.

package/templates/react-sdk-reference/.ai-common/global/ai-agent-instructions.md

@@ -20,16 +20,19 @@ This is a **reference implementation** — not a framework. The UI components (f
 | Template components directory | Layout templates (OneColumn, TwoColumn, Details, etc.)      |
 | Widget components directory   | Data widgets (ToDo, Attachment, CaseHistory, etc.)          |
 | DSE components directory      | Extended UI (AlertBanner, FieldGroup, RichTextEditor, etc.) |
+| Infra components directory    | Overridable chrome — ActionButtons, Stages, MultiStep only  |
 
 ### Infrastructure (do NOT modify unless you know what you're doing)
 
-| Area                         | Purpose                                   |
-| ---------------------------- | ----------------------------------------- |
-| Application bootstrap module | Auth + bootstrap + root rendering         |
-| Component map file           | Registry wiring (only add/remove entries) |
-| Infrastructure components    | ActionButtons, Stages, NavBar, etc.       |
-| Event handling helper module | PConnect event handler utility            |
-| SDK bridge package           | SDK bridge — never modify                 |
+| Area                         | Purpose                                          |
+| ---------------------------- | ------------------------------------------------ |
+| Application bootstrap module | Auth + bootstrap + root rendering                |
+| Component map file           | Registry wiring (only add/remove entries)        |
+| SDK-provided infra           | NavBar, DeferLoad, VerticalTabs, DashboardFilter |
+| Event handling helper module | PConnect event handler utility                   |
+| SDK bridge package           | SDK bridge — never modify                        |
+
+Infrastructure components are the chrome the runtime draws _around_ a case or an assignment. Most of them ship from the SDK adapter package and are never generated. Exactly three are overridable — `ActionButtons`, `Stages`, and `MultiStep` — because they render inline with the form, where SDK styling is the most visible mismatch. That list never grows.
 
 ---
 
@@ -182,11 +185,24 @@ Do not skip steps or proceed without reading the required skill files first.
 
 ---
 
-## 14. Generate All Components (Multi-Type)
+## 14. Batch Infrastructure Component Generation
+
+When the user asks to generate, create, or replace **infrastructure components**, **chrome components**, or **all infra components** with a design system (e.g., "generate infra components with Ant Design", "replace the infrastructure components with Chakra UI", "generate chrome components using Carbon"),
+read the full contents of `{{PROMPT_DIR}}/generate-infra-components{{PROMPT_EXT}}` and
+execute every step in order before writing any code.
+Do not skip steps or proceed without reading the required skill files first.
+
+> Only `ActionButtons`, `Stages`, and `MultiStep` may be generated. Every other infrastructure component is SDK-provided — if the user names one, skip it and say why. Infra entries in the component map must be listed **after** the SDK's built-in component spread, or the override silently does nothing.
+
+---
+
+## 15. Generate All Components (Multi-Type)
 
 When the user asks to generate, create, or replace components across **multiple types** or **all component types** at once (e.g., "generate all components with Ant Design", "replace everything with Chakra UI", "generate field and widget components using Carbon", "regenerate all components"),
 read the full contents of `{{PROMPT_DIR}}/generate-all-components{{PROMPT_EXT}}` and
 execute every step in order before writing any code.
 Do not skip steps or proceed without reading the required skill files first.
 
-> Use this section when the request spans more than one component type. For a single type, use Sections 10–13.
+> Use this section when the request spans more than one component type. For a single type, use Sections 10–14.
+>
+> That prompt does not generate the full catalogue. Its Step 0.5 is a mandatory gate: resolve the application's portals from the server, ask which one to generate for, ask whether to convert its landing pages, its cases, or both, resolve the components for whatever was chosen, and ask which of them to generate. Only the confirmed selection is generated.

package/templates/react-sdk-reference/.ai-common/instructions/infra-component.md

@@ -0,0 +1,76 @@
+---
+ai-globs: **/infra/**/*
+---
+
+# Infrastructure (Chrome) Component Rules
+
+When creating or modifying infrastructure components, follow these rules:
+
+## What Are Infrastructure Components?
+
+Infrastructure components are the chrome the Pega runtime draws _around_ a case or an assignment — the action button row, the stage progress indicator, the step navigation — rather than the fields inside it. They differ from every other category in one important way: **they already exist**. Generating one produces an override of the SDK's implementation.
+
+## What May Be Generated
+
+| Component     | Role                                                 | Generate? |
+| ------------- | ---------------------------------------------------- | --------- |
+| ActionButtons | The Cancel / Save / Submit row beneath an assignment | Yes       |
+| Stages        | The case stage progress indicator                    | Yes       |
+| MultiStep     | Step navigation within a multi-step assignment       | Yes       |
+
+⛔ `NavBar`, `DeferLoad`, `VerticalTabs`, and `DashboardFilter` are structural plumbing tied to the SDK's own internals. They are always sourced from the SDK adapter package and are **never** generated. If a request names one, skip it and say why. This list never grows.
+
+## Patterns
+
+### Display-only chrome (no PConnect accessor)
+
+Used for: ActionButtons
+
+Receives everything it needs as plain display props and reports interaction through a supplied callback. It holds no local state and reads nothing from the store. This is the one exception to the rule that every Pega component receives the PConnect accessor — do not add one to it.
+
+### Case-aware chrome (PConnect accessor, read-only)
+
+Used for: Stages
+
+Receives the accessor so it can read case state and localize, but never writes. Normalize the runtime's raw input through the SDK utility the component's skill file documents, read case-level state using the runtime's constants rather than literal property names, and derive a display model before rendering.
+
+### Container chrome (renders children)
+
+Used for: MultiStep
+
+Wraps the form content the runtime hands it and arranges other Pega components around it. Resolve every Pega sub-component through the project's component registry, derive which part of the structure is active from the runtime's state flags (applying the documented fallback when nothing is marked active), and forward the accessor, item key, button definitions, and press callback to the resolved sub-component unchanged.
+
+## The Contract Is Fixed
+
+Inputs, callback signatures, derivation logic, and localization come from the SDK component being replaced. **Only markup and styling are yours to change.**
+
+- Do not rename inputs or reshape callback signatures.
+- Treat every array input as optional and default it to empty.
+- Keep repeated elements stable — every item in a rendered collection needs a stable identity.
+
+## Localization
+
+Every label an infrastructure component renders comes from Pega, not from the component. Button and action labels resolve through the Pega locale utilities using the locale category the SDK component uses; case and stage names resolve through the localization service on the PConnect accessor. The value arriving in the input is a key, not display text — rendering it directly looks correct in an English environment and breaks in every other one.
+
+## Visual Preservation
+
+The replacement must look the same as the original component:
+
+1. **Read any `.css` file in the directory first.** Note every class's visual intent (spacing, sizing, colors, layout).
+2. Replicate those styles via the new design system's props/variants, inline styles, or by keeping the CSS import — whichever produces the closest match.
+3. Do NOT silently drop legacy styling utility classes — map each one to an equivalent style.
+
+## Registration
+
+⛔ **Ordering is load-bearing for this category.** An infra entry is an override of a component the SDK already contributes, so it must be listed **after** the SDK's built-in component spread. Listed before it, the spread replaces it and the override silently does nothing.
+
+Never remove the spread — it supplies the infrastructure components that are not overridable, and removing it breaks rendering entirely.
+
+## Key Rules
+
+- Only `ActionButtons`, `Stages`, and `MultiStep` may be generated
+- The three do not share an input shape — take each one's inputs from its own skill file
+- Chrome is display-only — these components report interaction through the callback they were given and never write to the store
+- Resolve sub-components from the registry, never by direct import, or customer overrides are discarded
+- Derive the display model from the runtime's raw inputs first, then render it — this is what keeps the component portable across design systems
+- Case chrome is not assignment chrome — `Stages` belongs to the case view and never appears inside an embedded assignment; `ActionButtons` and `MultiStep` do

package/templates/react-sdk-reference/.ai-common/mcp/claude-code.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "pega-{MCPRuleName}": {
+      "type": "http",
+      "url": "{InfinityURL}/app/{AppAlias}/api/service/v1/mcp/{MCPRuleInsKey}"
+    }
+  }
+}

package/templates/react-sdk-reference/.ai-common/mcp/copilot.mcp.json

@@ -0,0 +1,8 @@
+{
+  "servers": {
+    "pega-{MCPRuleName}": {
+      "type": "http",
+      "url": "{InfinityURL}/app/{AppAlias}/api/service/v1/mcp/{MCPRuleInsKey}"
+    }
+  }
+}

package/templates/react-sdk-reference/.ai-common/mcp/cursor.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "pega-{MCPRuleName}": {
+      "url": "{InfinityURL}/app/{AppAlias}/api/service/v1/mcp/{MCPRuleInsKey}",
+      "auth": {
+        "clientId": "{ClientId}",
+        "clientSecret": "<YOUR_CLIENT_SECRET>"
+      }
+    }
+  }
+}

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

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

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

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