@pega/sdk 0.0.4 → 0.0.5

package/dist/index.js

@@ -4,6 +4,7 @@
 import * as p from "@clack/prompts";
 import pc from "picocolors";
 import path2 from "path";
+import { createRequire } from "module";
 
 // src/scaffold.ts
 import fs from "fs";
@@ -361,6 +362,13 @@ async function scaffold(choices, targetDir, onProgress) {
         }
       }
       fs.writeFileSync(path.join(componentsDir, "component-map.ts"), generateMinimalComponentMap());
+      if (framework === "react") {
+        fs.writeFileSync(path.join(targetDir, "src", "AppProviders.tsx"), generateMinimalReactProviders());
+        const muiThemeAugmentation = path.join(targetDir, "src", "mui-theme-augmentation.d.ts");
+        if (fs.existsSync(muiThemeAugmentation)) {
+          fs.rmSync(muiThemeAugmentation);
+        }
+      }
     } else {
       const allCategories = ["fields", "templates", "widgets", "infra", "designSystemExtension"];
       for (const cat of allCategories) {
@@ -376,7 +384,7 @@ async function scaffold(choices, targetDir, onProgress) {
     }
   }
   if (!aiTool) {
-    for (const dir of [".github", ".cursor", "AGENTS.md", ".claude"]) {
+    for (const dir of [".github", ".cursor", "AGENTS.md", ".claude", ".ai-common"]) {
       const target = path.join(targetDir, dir);
       if (fs.existsSync(target)) {
         fs.rmSync(target, { recursive: true });
@@ -398,10 +406,13 @@ async function scaffold(choices, targetDir, onProgress) {
         }
       }
     }
+    generateAiConfigs(targetDir, aiTool);
   }
   report("Finalizing project configuration\u2026");
+  selectReactPackageManifest(targetDir, framework, includeTemplates, componentCategories);
   transformPackageJson(path.join(targetDir, "package.json"), projectName);
   transformTsConfig(path.join(targetDir, "tsconfig.json"));
+  transformSdkConfig(path.join(targetDir, "sdk-config.json"));
   report("Installing dependencies (this may take a minute)\u2026");
   try {
     await runInstall(targetDir);
@@ -429,6 +440,18 @@ function transformPackageJson(pkgJsonPath, projectName) {
   delete pkgJson.private;
   fs.writeFileSync(pkgJsonPath, JSON.stringify(pkgJson, null, 2) + "\n");
 }
+function selectReactPackageManifest(targetDir, framework, includeTemplates, componentCategories) {
+  if (framework !== "react") return;
+  const pkgJsonPath = path.join(targetDir, "package.json");
+  const minimalPkgJsonPath = path.join(targetDir, "package.minimal.json");
+  const hasSampleComponents = includeTemplates && componentCategories.length > 0;
+  if (!hasSampleComponents && fs.existsSync(minimalPkgJsonPath)) {
+    fs.copyFileSync(minimalPkgJsonPath, pkgJsonPath);
+  }
+  if (fs.existsSync(minimalPkgJsonPath)) {
+    fs.rmSync(minimalPkgJsonPath);
+  }
+}
 function transformTsConfig(tsconfigPath) {
   if (!fs.existsSync(tsconfigPath)) return;
   const tsconfig = JSON.parse(fs.readFileSync(tsconfigPath, "utf-8"));
@@ -453,6 +476,21 @@ function transformTsConfig(tsconfigPath) {
   }
   fs.writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2) + "\n");
 }
+function transformSdkConfig(sdkConfigPath) {
+  if (!fs.existsSync(sdkConfigPath)) return;
+  const sdkConfig = JSON.parse(fs.readFileSync(sdkConfigPath, "utf-8"));
+  if (sdkConfig.serverConfig) {
+    if ("infinityRestServerUrl" in sdkConfig.serverConfig) sdkConfig.serverConfig.infinityRestServerUrl = "";
+    if ("appAlias" in sdkConfig.serverConfig) sdkConfig.serverConfig.appAlias = "";
+    if ("appMashupCaseType" in sdkConfig.serverConfig) sdkConfig.serverConfig.appMashupCaseType = "";
+  }
+  if (sdkConfig.authConfig) {
+    if ("mashupClientId" in sdkConfig.authConfig) sdkConfig.authConfig.mashupClientId = "";
+    if ("mashupUserIdentifier" in sdkConfig.authConfig) sdkConfig.authConfig.mashupUserIdentifier = "";
+    if ("portalClientId" in sdkConfig.authConfig) sdkConfig.authConfig.portalClientId = "";
+  }
+  fs.writeFileSync(sdkConfigPath, JSON.stringify(sdkConfig, null, 2) + "\n");
+}
 function generateMinimalComponentMap() {
   return `import { sdkComponents } from '@pega/sdk-react';
 import type { ComponentRegistry } from '@pega/sdk-types';
@@ -480,6 +518,251 @@ export function registerSampleComponents(
 }
 `;
 }
+function generateMinimalReactProviders() {
+  return `import type { PropsWithChildren } from 'react';
+
+export function AppProviders({ children }: PropsWithChildren) {
+  return <>{children}</>;
+}
+`;
+}
+var AI_GEN_CONFIGS = {
+  copilot: {
+    skillDir: ".github/skills",
+    promptDir: ".github/prompts",
+    instructionsDir: ".github/instructions",
+    agentsDir: ".github/agents",
+    skillExt: "md",
+    promptExt: "prompt.md",
+    instructionsExt: "instructions.md",
+    agentExt: "agent.md",
+    tokens: {
+      "{{PROMPT_DIR}}": ".github/prompts",
+      "{{SKILL_DIR}}": ".github/skills",
+      "{{PROMPT_EXT}}": ".prompt.md",
+      "{{SKILL_EXT}}": ".md",
+      "{{AI_FILE_EXT}}": ".instructions.md"
+    }
+  },
+  "claude-code": {
+    skillDir: ".claude/skills",
+    promptDir: ".claude/prompts",
+    instructionsDir: ".claude/instructions",
+    agentsDir: ".claude/agents",
+    skillExt: "md",
+    promptExt: "md",
+    instructionsExt: "md",
+    agentExt: "md",
+    tokens: {
+      "{{PROMPT_DIR}}": ".claude/prompts",
+      "{{SKILL_DIR}}": ".claude/skills",
+      "{{PROMPT_EXT}}": ".md",
+      "{{SKILL_EXT}}": ".md",
+      "{{AI_FILE_EXT}}": ".md"
+    }
+  },
+  cursor: {
+    skillDir: ".cursor/rules/skills",
+    promptDir: ".cursor/rules/prompts",
+    instructionsDir: ".cursor/rules",
+    agentsDir: ".cursor/rules/agents",
+    skillExt: "mdrules",
+    promptExt: "mdrules",
+    instructionsExt: "mdrules",
+    agentExt: "mdrules",
+    tokens: {
+      "{{PROMPT_DIR}}": ".cursor/rules/prompts",
+      "{{SKILL_DIR}}": ".cursor/rules/skills",
+      "{{PROMPT_EXT}}": ".mdrules",
+      "{{SKILL_EXT}}": ".mdrules",
+      "{{AI_FILE_EXT}}": ".mdrules"
+    }
+  }
+};
+function parseAiMeta(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n\n?/);
+  if (!match) return { meta: {}, body: content };
+  const meta = {};
+  for (const line of match[1].split("\n")) {
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    const val = line.slice(colonIdx + 1).trim().replace(/^"|"$/g, "");
+    if (key.startsWith("ai-")) meta[key.slice(3)] = val;
+  }
+  return { meta, body: content.slice(match[0].length) };
+}
+function applyTokens(content, tokens) {
+  let result = content;
+  for (const [token, value] of Object.entries(tokens)) {
+    result = result.split(token).join(value);
+  }
+  return result;
+}
+function cursorSkillDescription(relPath) {
+  const parts = relPath.split("/");
+  if (parts.length >= 2) {
+    const subdir = parts[parts.length - 2];
+    const name = parts[parts.length - 1].replace(/\.md$/, "");
+    if (subdir === "field-skills") return `Field component skill: ${name}`;
+    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}`;
+  }
+  return relPath.replace(/\.md$/, "").split("/").pop();
+}
+function generateAiConfigs(targetDir, aiTool) {
+  const aiCommonDir = path.join(targetDir, ".ai-common");
+  if (!fs.existsSync(aiCommonDir)) return;
+  const cfg = AI_GEN_CONFIGS[aiTool];
+  const { tokens } = cfg;
+  const skillsSrc = path.join(aiCommonDir, "skills");
+  if (fs.existsSync(skillsSrc)) {
+    let processSkillsDir2 = function(srcDir, relDir = "") {
+      for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+        const relPath = relDir ? `${relDir}/${entry.name}` : entry.name;
+        const srcPath = path.join(srcDir, entry.name);
+        if (entry.isDirectory()) {
+          processSkillsDir2(srcPath, relPath);
+        } else if (entry.name.endsWith(".md")) {
+          const { body } = parseAiMeta(fs.readFileSync(srcPath, "utf-8"));
+          const outContent = applyTokens(body, tokens);
+          let frontmatter = "";
+          if (aiTool === "cursor") {
+            const desc = cursorSkillDescription(relPath);
+            frontmatter = `---
+description: ${desc}
+alwaysApply: false
+---
+
+`;
+          }
+          const outName = `${entry.name.replace(/\.md$/, "")}.${cfg.skillExt}`;
+          const outDir = path.join(targetDir, cfg.skillDir, relDir);
+          fs.mkdirSync(outDir, { recursive: true });
+          fs.writeFileSync(path.join(outDir, outName), frontmatter + outContent);
+        }
+      }
+    };
+    var processSkillsDir = processSkillsDir2;
+    processSkillsDir2(skillsSrc);
+  }
+  const promptsSrc = path.join(aiCommonDir, "prompts");
+  if (fs.existsSync(promptsSrc)) {
+    const promptsDest = path.join(targetDir, cfg.promptDir);
+    fs.mkdirSync(promptsDest, { recursive: true });
+    for (const entry of fs.readdirSync(promptsSrc, { withFileTypes: true })) {
+      const srcPath = path.join(promptsSrc, entry.name);
+      if (entry.name === "component-manifest.json") {
+        fs.copyFileSync(srcPath, path.join(promptsDest, entry.name));
+      } else if (entry.name.endsWith(".md")) {
+        const { meta, body } = parseAiMeta(fs.readFileSync(srcPath, "utf-8"));
+        const outContent = applyTokens(body, tokens);
+        const basename = entry.name.replace(/\.md$/, "");
+        let frontmatter = "";
+        if (aiTool === "copilot") {
+          frontmatter = `---
+agent: agent
+description: ${meta.description || basename}
+---
+
+`;
+        } else if (aiTool === "cursor") {
+          frontmatter = `---
+description: Workflow prompt: ${basename}
+alwaysApply: false
+---
+
+`;
+        }
+        fs.writeFileSync(path.join(promptsDest, `${basename}.${cfg.promptExt}`), frontmatter + outContent);
+      }
+    }
+  }
+  const instructionsSrc = path.join(aiCommonDir, "instructions");
+  if (fs.existsSync(instructionsSrc)) {
+    const instructionsDest = path.join(targetDir, cfg.instructionsDir);
+    fs.mkdirSync(instructionsDest, { recursive: true });
+    for (const entry of fs.readdirSync(instructionsSrc, { withFileTypes: true })) {
+      if (!entry.name.endsWith(".md")) continue;
+      const { meta, body } = parseAiMeta(fs.readFileSync(path.join(instructionsSrc, entry.name), "utf-8"));
+      const outContent = applyTokens(body, tokens);
+      const basename = entry.name.replace(/\.md$/, "");
+      let frontmatter = "";
+      if (aiTool === "cursor") {
+        frontmatter = meta.globs ? `---
+globs: ["${meta.globs}"]
+---
+
+` : `---
+alwaysApply: false
+---
+
+`;
+      } else if (aiTool === "copilot") {
+        if (meta.globs) frontmatter = `---
+applyTo: '${meta.globs}'
+---
+
+`;
+      }
+      fs.writeFileSync(path.join(instructionsDest, `${basename}.${cfg.instructionsExt}`), frontmatter + outContent);
+    }
+  }
+  const agentsSrc = path.join(aiCommonDir, "agents");
+  if (fs.existsSync(agentsSrc)) {
+    const agentsDest = path.join(targetDir, cfg.agentsDir);
+    fs.mkdirSync(agentsDest, { recursive: true });
+    for (const entry of fs.readdirSync(agentsSrc, { withFileTypes: true })) {
+      if (!entry.name.endsWith(".md")) continue;
+      const basename = entry.name.replace(/\.md$/, "");
+      const srcPath = path.join(agentsSrc, entry.name);
+      const { meta, body } = parseAiMeta(fs.readFileSync(srcPath, "utf-8"));
+      const outContent = applyTokens(body, tokens);
+      let frontmatter = "";
+      if (aiTool === "copilot") {
+        const description = applyTokens(meta.description || "", tokens);
+        const name = meta.name || basename.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+        frontmatter = `---
+description: "${description}"
+name: '${name}'
+tools: [read, edit, search, execute, agent, vscode_askQuestions]
+user-invocable: true
+disable-model-invocation: false
+---
+
+`;
+      } else if (aiTool === "cursor") {
+        const description = applyTokens(meta.description || `Agent config: ${basename}`, tokens);
+        frontmatter = `---
+description: ${description}
+alwaysApply: false
+---
+
+`;
+      }
+      fs.writeFileSync(path.join(agentsDest, `${basename}.${cfg.agentExt}`), frontmatter + outContent);
+    }
+  }
+  const globalSrc = path.join(aiCommonDir, "global");
+  if (fs.existsSync(globalSrc)) {
+    const instructionsSrc2 = path.join(globalSrc, "ai-agent-instructions.md");
+    if (fs.existsSync(instructionsSrc2)) {
+      const content = applyTokens(fs.readFileSync(instructionsSrc2, "utf-8"), tokens);
+      if (aiTool === "copilot") {
+        fs.mkdirSync(path.join(targetDir, ".github"), { recursive: true });
+        fs.writeFileSync(path.join(targetDir, ".github", "copilot-instructions.md"), content);
+      } else if (aiTool === "cursor") {
+        fs.mkdirSync(path.join(targetDir, ".cursor", "rules"), { recursive: true });
+        const fm = "---\ndescription: Core rules for working with Pega SDK components\nalwaysApply: true\n---\n\n";
+        fs.writeFileSync(path.join(targetDir, ".cursor", "rules", "pega-sdk.mdrules"), fm + content);
+      } else if (aiTool === "claude-code") {
+        fs.writeFileSync(path.join(targetDir, "AGENTS.md"), content);
+      }
+    }
+  }
+  fs.rmSync(aiCommonDir, { recursive: true });
+}
 function copyDir(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
@@ -495,9 +778,12 @@ function copyDir(src, dest) {
 }
 
 // src/index.ts
+var require2 = createRequire(import.meta.url);
+var { version: sdkVersion } = require2("../package.json");
 async function main() {
   console.clear();
   p.intro(pc.bgCyan(pc.black(" @pega/sdk ")));
+  p.log.info(`Using @pega/sdk v${sdkVersion}`);
   const args = process.argv.slice(2);
   const command = args[0];
   if (command !== "init") {

package/package.json

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

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

@@ -9,23 +9,23 @@
     "dev": "ng serve --open"
   },
   "dependencies": {
-    "@angular/animations": "^22.0.6",
-    "@angular/common": "^22.0.6",
-    "@angular/compiler": "^22.0.6",
-    "@angular/core": "^22.0.6",
-    "@angular/forms": "^22.0.6",
-    "@angular/platform-browser": "^22.0.6",
-    "@angular/platform-browser-dynamic": "^22.0.6",
-    "@angular/router": "^22.0.6",
+    "@angular/animations": "^21.2.0",
+    "@angular/common": "^21.2.0",
+    "@angular/compiler": "^21.2.0",
+    "@angular/core": "^21.2.0",
+    "@angular/forms": "^21.2.0",
+    "@angular/platform-browser": "^21.2.0",
+    "@angular/platform-browser-dynamic": "^21.2.0",
+    "@angular/router": "^21.2.0",
     "@pega/sdk-angular": "^0.1.0",
     "rxjs": "~7.8.2",
     "tslib": "^2.8.1",
     "zone.js": "~0.16.2"
   },
   "devDependencies": {
-    "@angular-devkit/build-angular": "^22.0.6",
-    "@angular/cli": "^22.0.6",
-    "@angular/compiler-cli": "^22.0.6",
-    "typescript": "~6.0.3"
+    "@angular-devkit/build-angular": "^21.2.0",
+    "@angular/cli": "^21.2.0",
+    "@angular/compiler-cli": "^21.2.0",
+    "typescript": "~5.9.3"
   }
 }

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

@@ -21,7 +21,7 @@
       "@pega/sdk-angular": ["../../packages/sdk-angular/src/index.ts"],
       "@pega/sdk-types": ["../../packages/sdk-types/src/index.ts"]
     },
-    "ignoreDeprecations": "6.0"
+    "ignoreDeprecations": "5.0"
   },
   "angularCompilerOptions": {
     "enableI18nLegacyMessageIdFormat": false,

package/templates/react-native-sdk-reference/expo-env.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="expo/types" />
+
+// NOTE: This file should not be edited and should be in your git ignore

package/templates/react-sdk-reference/{.github/agents/implementation-expert.agent.md → .ai-common/agents/implementation-expert.md}

@@ -1,13 +1,10 @@
 ---
-description: "Use when the user wants to generate, create, add, replace, migrate, or identify UI components (field, template, widget, design system extension, or infra) in this Pega SDK reference app — a single component, a batch, or the entire app — with any design system (Ant Design, Chakra UI, Radix, Shadcn, Carbon, MUI, etc.). Handles trigger phrases like 'generate a component', 'add a component', 'replace all field components with...', 'migrate the design system to...', 'replace everything with...', 'what components are in this screenshot'. Executes the repo's existing .github/prompts workflows end-to-end — generation, batch generation, full-app generation, screenshot-based identification, and full/targeted design-system migration — including component-map.ts registration, provider setup, and build verification."
-name: 'Implementation Expert'
-tools: [read, edit, search, execute, agent, vscode_askQuestions]
-user-invocable: true
-disable-model-invocation: false
+ai-name: Implementation Expert
+ai-description: "Use when the user wants to generate, create, add, replace, migrate, or identify UI components (field, template, widget, design system extension, or infra) in this Pega SDK reference app — a single component, a batch, or the entire app — with any design system (Ant Design, Chakra UI, Radix, Shadcn, Carbon, MUI, etc.). Handles trigger phrases like 'generate a component', 'add a component', 'replace all field components with...', 'migrate the design system to...', 'replace everything with...', 'what components are in this screenshot'. Executes the repo's existing {{PROMPT_DIR}} workflows end-to-end — generation, batch generation, full-app generation, screenshot-based identification, and full/targeted design-system migration — including component-map.ts registration, provider setup, and build verification."
 ---
 
 You are the **Implementation Expert** for this Pega Infinity SDK React reference application. You are not limited
-to generating new components — you implement the **entire component lifecycle flow** defined in `.github/prompts/`:
+to generating new components — you implement the **entire component lifecycle flow** defined in `{{PROMPT_DIR}}/`:
 creating components, batch-generating them, generating the whole app, identifying components from screenshots, and
 migrating the design system of components that already exist. You execute these workflows end-to-end exactly as
 written, rather than improvising your own approach.
@@ -57,31 +54,31 @@ 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")                                                           | `.github/prompts/add-component.prompt.md`                                                                                                                                                                 |
-| Multiple/all field components, one design system                                                                                                    | `.github/prompts/generate-field-components.prompt.md`                                                                                                                                                     |
-| Multiple/all template components, one design system                                                                                                 | `.github/prompts/generate-template-components.prompt.md`                                                                                                                                                  |
-| Multiple/all widget components, one design system                                                                                                   | `.github/prompts/generate-widget-components.prompt.md`                                                                                                                                                    |
-| Multiple/all design system extension components, one design system                                                                                  | `.github/prompts/generate-dse-components.prompt.md`                                                                                                                                                       |
-| Multiple component types at once, or "generate all components"                                                                                      | `.github/prompts/generate-all-components.prompt.md` (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)                                        | `.github/prompts/identify-components.prompt.md` — 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 | `.github/prompts/replace-design-system.prompt.md` (reads `.github/prompts/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 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) |
 
 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
 doesn't exist yet (or is being fully rewritten), migration assumes it exists and only its design-system primitives
 change.
 
-### Migration-specific notes (`replace-design-system.prompt.md`)
+### Migration-specific notes (`replace-design-system{{PROMPT_EXT}}`)
 
 - 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 `.github/prompts/`.** When launching those
+  `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 (`.github/skills/field-components.md`, `template-components.md`, `widget-components.md`, or
+  general skill (`{{SKILL_DIR}}/field-components.md`, `template-components.md`, `widget-components.md`, or
   `design-system-extension.md`), the component-specific skill file
-  (`.github/skills/{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.md` uses for a single
+  (`{{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.
 - Root provider setup (Step T1.3 / 1.3) and `FieldValueList` replacement (Step T1.4 / 1.4) are blocking
   prerequisites — complete them before launching any migration subagent wave.
@@ -89,7 +86,7 @@ change.
 ## Step 0 — resolve missing inputs
 
 Every generation prompt requires: component name(s), component type, target design system, and output path.
-`replace-design-system.prompt.md` requires a target design system plus at least one way to resolve scope
+`replace-design-system{{PROMPT_EXT}}` requires a target design system plus at least one way to resolve scope
 (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
@@ -102,17 +99,17 @@ design system or silently default to MUI.
 - **One folder per component — never a shared/monolithic file.** Every component (field, template, widget, or
   designSystemExtension) must be created at `<outputPath>/<ComponentName>/<ComponentName>.tsx` plus a sibling
   `<outputPath>/<ComponentName>/index.tsx` that does `export { default } from './<ComponentName>';` — exactly as
-  Step 5/6 of `add-component.prompt.md` specifies. Never write multiple components into one `.tsx` file, never
+  Step 5/6 of `add-component{{PROMPT_EXT}}` specifies. Never write multiple components into one `.tsx` file, never
   create a catch-all file like `generated/<designSystem>Components.tsx`, and never export a single bundled object
   (e.g. `generatedComponents`) that `component-map.ts` 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.md` — the
+  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.
 - `component-map.ts` 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
   object.
 - Never modify the auth/bootstrap logic in `src/MashupApp.tsx`/`src/PortalApp.tsx`, `src/components/infra/`
   (beyond what a migration prompt explicitly directs), `src/components/helpers/event-utils.ts`, or anything under
-  `@pega/sdk-react`. The one exception: `replace-design-system.prompt.md` explicitly requires wrapping the
+  `@pega/sdk-react`. The one exception: `replace-design-system{{PROMPT_EXT}}` explicitly requires wrapping the
   existing provider tree in `MashupApp.tsx`/`PortalApp.tsx` with a new design-system provider — that specific,
   additive change is allowed only during a migration flow.
 - Never remove the `...sdkComponents` spread in `src/components/component-map.ts` — only add or replace entries.
@@ -127,7 +124,7 @@ design system or silently default to MUI.
 
 ## Verification
 
-After generation or migration, run the build (`npm run build`, or the steps in `.github/skills/run-and-verify.md`
+After generation or migration, run the build (`npm run build`, or the steps in `{{SKILL_DIR}}/run-and-verify{{SKILL_EXT}}`
 if the prompt references it) and report the result. Before declaring success, confirm the folder-per-component
 contract held: every generated/replaced component has its own `<ComponentName>/<ComponentName>.tsx` +
 `<ComponentName>/index.tsx`, and no monolithic/shared/"generated" bundle file was created. Summarize: which

package/templates/react-sdk-reference/{.github/copilot-instructions.md → .ai-common/global/ai-agent-instructions.md}

@@ -1,4 +1,4 @@
-# Copilot Instructions — React SDK Reference
+# Pega SDK — React Reference App
 
 You are assisting developers in a React reference application that demonstrates the Pega Infinity SDK. Customers clone this repo and **replace the sample UI components with their own design system** (MUI, Chakra, Radix, Shadcn, Ant Design, or any other).
 
@@ -189,7 +189,7 @@ import handleEvent from '../../helpers/event-utils';
 ## 9. Component Generation Workflow — Single Component
 
 When the user asks to generate, create, add, or replace **a single UI component** (e.g., "generate an AutoComplete component", "add a Dropdown using Chakra UI"),
-read the full contents of `.github/prompts/add-component.prompt.md` and
+read the full contents of `{{PROMPT_DIR}}/add-component{{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.
 
@@ -200,7 +200,7 @@ Do not skip steps or proceed without reading the required skill files first.
 ## 10. Batch Field Component Generation
 
 When the user asks to generate, create, or replace **multiple field components** or **all field components** with a design system (e.g., "generate field components with Ant Design", "replace all fields with Chakra UI", "generate all field components using Radix"),
-read the full contents of `.github/prompts/generate-field-components.prompt.md` and
+read the full contents of `{{PROMPT_DIR}}/generate-field-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.
 
@@ -209,7 +209,7 @@ Do not skip steps or proceed without reading the required skill files first.
 ## 11. Batch Template Component Generation
 
 When the user asks to generate, create, or replace **multiple template components** or **all template components** with a design system (e.g., "generate template components with Ant Design", "replace all templates with Chakra UI", "generate layout templates using Radix"),
-read the full contents of `.github/prompts/generate-template-components.prompt.md` and
+read the full contents of `{{PROMPT_DIR}}/generate-template-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.
 
@@ -218,7 +218,7 @@ Do not skip steps or proceed without reading the required skill files first.
 ## 12. Batch Widget Component Generation
 
 When the user asks to generate, create, or replace **multiple widget components** or **all widget components** with a design system (e.g., "generate widget components with Ant Design", "replace all widgets with Chakra UI", "generate widgets using Carbon"),
-read the full contents of `.github/prompts/generate-widget-components.prompt.md` and
+read the full contents of `{{PROMPT_DIR}}/generate-widget-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.
 
@@ -227,7 +227,7 @@ Do not skip steps or proceed without reading the required skill files first.
 ## 13. Batch Design System Extension Component Generation
 
 When the user asks to generate, create, or replace **multiple design system extension components** or **all DSE components** with a design system (e.g., "generate DSE components with Ant Design", "replace design system extension components with Chakra UI", "generate designSystemExtension components using Carbon"),
-read the full contents of `.github/prompts/generate-dse-components.prompt.md` and
+read the full contents of `{{PROMPT_DIR}}/generate-dse-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.
 
@@ -236,7 +236,7 @@ Do not skip steps or proceed without reading the required skill files first.
 ## 14. 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 `.github/prompts/generate-all-components.prompt.md` and
+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.
 

package/templates/react-sdk-reference/{.github/instructions/component-map.instructions.md → .ai-common/instructions/component-map.md}

@@ -1,5 +1,5 @@
 ---
-applyTo: '**/component-map.ts'
+ai-globs: **/component-map.ts
 ---
 
 # Component Map Rules
@@ -38,3 +38,10 @@ function getSampleComponentMap() {
    - `Todo: ToDo` (casing difference)
 
 6. **Keep the `registerSampleComponents` function** — it registers all entries into the `ComponentRegistry` instance used by the PConnect bridge.
+
+7. **Sub-component registration** — Some template/widget components internally render sub-components via `getComponentFromRegistry()`. These sub-components MUST also be registered in the component map or they will be `undefined` at runtime. Known sub-components:
+   - `SearchForm` — used by `DataReference` and `AdvancedSearch`
+   - `SearchGroups` — used by `AdvancedSearch`
+   - `ActionButtonsForFileUtil` — used by `FileUtility`
+
+8. **`Todo` vs `ToDo` key** — The Pega engine sends `Todo` (capital T, lowercase odo). The component variable may be named `ToDo`, but the map key MUST be `Todo: ToDo`.

package/templates/react-sdk-reference/{.github/instructions/dse-component.instructions.md → .ai-common/instructions/dse-component.md}

@@ -1,5 +1,5 @@
 ---
-applyTo: 'src/components/designSystemExtension/**/*.tsx'
+ai-globs: src/components/designSystemExtension/**/*.tsx
 ---
 
 # Design System Extension Component Rules

package/templates/react-sdk-reference/{.github/instructions/field-component.instructions.md → .ai-common/instructions/field-component.md}

@@ -1,5 +1,5 @@
 ---
-applyTo: 'src/components/field/**/*.tsx'
+ai-globs: src/components/field/**/*.tsx
 ---
 
 # Field Component Rules
@@ -75,3 +75,4 @@ The replacement must look the same as the original component:
 - Hardcode component imports for components that exist in the registry
 - Remove the `handleEvent` import from `../../helpers/event-utils`
 - Drop visual styles when removing `makeStyles` — always map them to an equivalent
+- **Import the same symbol twice from `field-utils`** — if you import `DynamicFieldProps` (or any other export) in one import statement, do NOT add a separate `import type { DynamicFieldProps }` line. This causes `"DynamicFieldProps is already defined"` errors. Use a single import: `import { commitField, DynamicFieldProps, FieldValue, getFieldContext } from '../field-utils';`

package/templates/react-sdk-reference/{.github/instructions/template-component.instructions.md → .ai-common/instructions/template-component.md}

@@ -1,5 +1,5 @@
 ---
-applyTo: 'src/components/template/**/*.tsx'
+ai-globs: src/components/template/**/*.tsx
 ---
 
 # Template Component Rules

package/templates/react-sdk-reference/{.github/instructions/widget-component.instructions.md → .ai-common/instructions/widget-component.md}

@@ -1,5 +1,5 @@
 ---
-applyTo: 'src/components/widget/**/*.tsx'
+ai-globs: src/components/widget/**/*.tsx
 ---
 
 # Widget Component Rules