@pega/sdk 0.0.10 → 0.0.13

package/README.md

@@ -15,10 +15,12 @@ has a project in it:
   said while working inside an existing host application) → run in that
   **existing project's folder**.
 
-In both cases, run `npx @pega/sdk init` non-interactively — see
+In both cases, run `npx --yes @pega/sdk init` non-interactively — see
 [Non-Interactive / Scripted Usage](#non-interactive--scripted-usage) below for the
 full flag reference. Gather answers conversationally, then invoke one command; do
-not try to drive the interactive prompts through a terminal.
+not try to drive the interactive prompts through a terminal. The leading `npx
+--yes` matters: without it, npx's own install confirmation blocks before this CLI
+even starts.
 
 Mode is decided by the folder you run the command in, not something you need to ask
 about or guess:
@@ -32,13 +34,15 @@ about or guess:
 | Decide yourself (don't ask the user)                                                                                | Ask the user (can't be inferred)                         |
 | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
 | `--mode` (auto-detected from whether `package.json` exists in the cwd)                                              | none — these are all optional and not needed to scaffold |
-| `--ai-tool` (you know which tool you are)                                                                           |                                                          |
+| `--ai-tool` (set it to yourself: GitHub Copilot → `copilot`, Cursor → `cursor`, Claude Code → `claude-code`)        |                                                          |
 | `--framework`, `--name`, `--templates`, `--categories` (infer from the request, or ask only if genuinely ambiguous) |                                                          |
 
-`--server-url` / `--app-alias` / `--client-id` / `--mcp-rule-name` / `--mcp-rule-ins-key`
-are optional, CI-only flags. Do not prompt the user for them at scaffold time —
-they're configured afterward by editing `sdk-config.json` and the generated MCP
-config file directly (see [Configure Your Pega Server](#configure-your-pega-server)).
+Server connection details (Pega server URL, app alias, OAuth client ID, MCP rule
+name/instance key) are never asked at scaffold time, in either mode — the scaffold
+always leaves `sdk-config.json` blank and the generated MCP config file with its
+placeholder markers. An AI coding assistant gathers these from the user in chat
+and fills both files in automatically the first time a workflow needs them (see
+[Configure Your Pega Server](#configure-your-pega-server)).
 
 ## Requirements
 
@@ -46,6 +50,22 @@ config file directly (see [Configure Your Pega Server](#configure-your-pega-serv
 - **npm** 9 or later
 - Access to a Pega Infinity server (for running the generated app)
 
+## Non-Interactive / Scripted Usage
+
+Pass any flag to `init` to scaffold in one shot, with no prompts:
+
+```bash
+# New project
+npx --yes @pega/sdk init --name my-app --framework react --ai-tool copilot --templates false
+
+# Embedded flow, inside an existing project
+npx --yes @pega/sdk init --mode embedded --ai-tool cursor --conflict-policy merge
+```
+
+Run `npx --yes @pega/sdk init --help` for the full flag reference (`--help` also
+works without the `init` subcommand). On invalid or missing required input, the
+CLI prints an error to stderr and exits with a non-zero code — no hanging prompt.
+
 ## Quick Start
 
 ```bash
@@ -94,27 +114,10 @@ If you skip starter components in a React project, the scaffold uses a minimal
 dependency manifest for a lighter baseline app.
 
 Server connection details (Pega server URL, app alias, OAuth client ID) and MCP
-rule details are no longer asked interactively — edit `sdk-config.json` and the
-generated MCP config file after scaffolding (see below).
-
-## Non-Interactive / Scripted Usage
-
-Pass any flag to `init` (or `--json`) to scaffold in one shot, with no prompts:
-
-```bash
-# New project
-npx @pega/sdk init --name my-app --framework react --ai-tool copilot --templates false --yes
-
-# Embedded flow, inside an existing project
-npx @pega/sdk init --mode embedded --ai-tool copilot --conflict-policy merge
-
-# Or supply everything via a JSON answers file (values here win over individual flags)
-npx @pega/sdk init --json ./sdk-answers.json
-```
-
-Run `npx @pega/sdk init --help` for the full flag reference. On invalid or
-missing required input, the CLI prints an error to stderr and exits with a
-non-zero code — no hanging prompt.
+rule details are never asked — neither interactively nor as CLI flags. Configure
+them after scaffolding, either by asking your AI coding assistant (it gathers them
+in chat and fills in both files automatically) or by editing `sdk-config.json` and
+the generated MCP config file yourself (see below).
 
 ## What You Get
 
@@ -129,8 +132,31 @@ The generated project is ready to run and includes:
 
 ## Configure Your Pega Server
 
-Before running the app, edit `sdk-config.json` in the project root with your
-environment details:
+The scaffolded project ships with `sdk-config.json` and a generated MCP config file
+both intentionally blank/placeholder — connection details are never collected at
+scaffold time. The same setup applies to full-portal and embedded projects.
+
+**AI coding assistant (recommended):** the first workflow that needs a live Pega
+server checks the active `sdk-config.json`, the generated MCP config, and project-root
+`.env*` files. It asks once for every missing non-secret value. You can provide those
+values in chat or update an allowed file yourself; the assistant then synchronizes
+all applicable destinations and asks again only for values that remain missing.
+
+**Manual or environment setup:** configure the following non-secret values in any
+applicable source:
+
+| Value                 | Environment key example | `sdk-config.json`                                           | MCP config                             |
+| --------------------- | ----------------------- | ----------------------------------------------------------- | -------------------------------------- |
+| Pega server URL       | `PEGA_INFINITY_URL`     | `serverConfig.infinityRestServerUrl`                        | `{InfinityURL}` in the URL             |
+| Application alias     | `PEGA_APP_ALIAS`        | `serverConfig.appAlias`                                     | `{AppAlias}` in the URL                |
+| MCP rule name         | `PEGA_MCP_RULE_NAME`    | —                                                           | `{MCPRuleName}` in the server key      |
+| MCP rule instance key | `PEGA_MCP_RULE_INS_KEY` | —                                                           | `{MCPRuleInsKey}` in the URL           |
+| OAuth client ID       | `PEGA_CLIENT_ID`        | `authConfig.mashupClientId` and `authConfig.portalClientId` | Cursor's `auth.clientId`, when present |
+
+For full-portal projects, use the scaffolded application `sdk-config.json`. For
+embedded projects, use the copy in the host framework's browser-served static
+directory (for example `public/sdk-config.json`), not a stale same-named root copy.
+Its relevant structure is:
 
 ```jsonc
 {
@@ -153,6 +179,16 @@ environment details:
 - `appAlias` — the application alias to load
 - `mashupClientId` / `portalClientId` — OAuth 2.0 client IDs registered in Pega
 
+The generated MCP file is `.vscode/mcp.json` for Copilot, `.cursor/mcp.json` for
+Cursor, or `.mcp.json` for Claude Code. Copilot and Claude Code use URL-only MCP
+configuration and do not require a client secret. Cursor's authenticated MCP entry
+also requires `auth.clientId` and `auth.clientSecret`. The Pega MCP client secret
+must come from a private project-root environment variable such as
+`PEGA_CLIENT_SECRET`; never provide it in chat, use a browser-exposed environment
+name (`VITE_*`, `NEXT_PUBLIC_*`, `REACT_APP_*`, or `EXPO_PUBLIC_*`), or put it in
+browser-served `sdk-config.json`. The assistant reads the private environment value
+and writes it only to Cursor's `auth.clientSecret`.
+
 ## Available Scripts
 
 Inside the generated project:

package/dist/index.js

@@ -1020,16 +1020,9 @@ function generateAiConfigs(targetDir, choices) {
   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) {
+    const { config: mcpConfig, destRelPath: mcpDestRelPath } = resolveMcpConfig(aiCommonDir, choices.aiTool);
+    writeManagedJson(path2.join(targetDir, mcpDestRelPath), mcpConfig, "override");
     if (choices.aiTool === "cursor") {
       ensureGitignoreEntry(targetDir, mcpDestRelPath);
     }
@@ -1046,27 +1039,18 @@ function resolveEmbeddedSource() {
   }
   return { sampleDir, aiCommonSrc };
 }
-var SDK_CONFIG_USER_KEYS = [];
-var MCP_CONFIG_USER_KEYS = [];
 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];
+function resolveMcpConfig(aiCommonSrc, aiTool) {
+  const { source, dest } = MCP_CONFIG_FILES[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 = {};
-  if (choices.serverUrl) tokens["{InfinityURL}"] = choices.serverUrl;
-  if (choices.appAlias) tokens["{AppAlias}"] = choices.appAlias;
-  if (choices.clientId) tokens["{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 };
+  return { config: JSON.parse(fs2.readFileSync(srcPath, "utf-8")), destRelPath: dest };
 }
 function ensureGitignoreEntry(targetDir, entry) {
   const gitignorePath = path2.join(targetDir, ".gitignore");
@@ -1075,11 +1059,11 @@ function ensureGitignoreEntry(targetDir, entry) {
   const separator = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
   fs2.writeFileSync(gitignorePath, existing + separator + entry + "\n");
 }
-function buildSdkConfig(choices) {
+function buildSdkConfig() {
   return {
     serverConfig: {
-      infinityRestServerUrl: choices.serverUrl ?? "",
-      appAlias: choices.appAlias ?? "",
+      infinityRestServerUrl: "",
+      appAlias: "",
       sdkContentServerUrl: "",
       appPortal: "",
       appMashupCaseType: "",
@@ -1094,10 +1078,10 @@ function buildSdkConfig(choices) {
     },
     authConfig: {
       authService: "pega",
-      mashupClientId: choices.clientId ?? "",
+      mashupClientId: "",
       mashupUserIdentifier: "",
       mashupPassword: "",
-      portalClientId: choices.clientId ?? "",
+      portalClientId: "",
       portalClientSecret: "",
       portalGrantType: ""
     }
@@ -1115,12 +1099,12 @@ function collectEmbeddedConflicts(targetDir, choices) {
     }
   }).map((file) => file.destPath);
   const sdkConfigPath = path2.join(resolveStaticDir(targetDir), "sdk-config.json");
-  if (isConflict(sdkConfigPath, buildSdkConfig(choices), SDK_CONFIG_USER_KEYS)) {
+  if (isConflict(sdkConfigPath, buildSdkConfig())) {
     conflicts.push(sdkConfigPath);
   }
-  const { config: mcpConfig, destRelPath: mcpDestRelPath } = resolveMcpConfig(aiCommonSrc, choices);
+  const { config: mcpConfig, destRelPath: mcpDestRelPath } = resolveMcpConfig(aiCommonSrc, choices.aiTool);
   const mcpConfigPath = path2.join(targetDir, mcpDestRelPath);
-  if (isConflict(mcpConfigPath, mcpConfig, MCP_CONFIG_USER_KEYS)) {
+  if (isConflict(mcpConfigPath, mcpConfig)) {
     conflicts.push(mcpConfigPath);
   }
   return conflicts.map((filePath) => path2.relative(targetDir, filePath));
@@ -1169,13 +1153,13 @@ async function scaffoldEmbedded(choices, targetDir, onProgress) {
   report("Creating SDK configuration\u2026");
   const staticDir = ensureStaticDir(targetDir);
   const sdkConfigPath = path2.join(staticDir, "sdk-config.json");
-  writeManagedJson(sdkConfigPath, buildSdkConfig(choices), policy, SDK_CONFIG_USER_KEYS);
+  writeManagedJson(sdkConfigPath, buildSdkConfig(), policy);
   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);
+  const { config: mcpConfig, destRelPath: mcpDestRelPath } = resolveMcpConfig(aiCommonSrc, aiTool);
+  writeManagedJson(path2.join(targetDir, mcpDestRelPath), mcpConfig, policy);
   if (aiTool === "cursor") {
     ensureGitignoreEntry(targetDir, mcpDestRelPath);
   }
@@ -1250,23 +1234,46 @@ var AI_TOOLS = ["copilot", "cursor", "claude-code"];
 var PROJECT_NAME_RE = /^[a-z0-9@][a-z0-9._/-]*$/;
 var CliValidationError = class extends Error {
 };
+var AI_TOOL_CHOICES = AI_TOOLS.join("|");
+var FRAMEWORK_CHOICES = FRAMEWORKS.join("|");
+var AGENT_QUICKSTART = `
+AI coding agents (GitHub Copilot, Cursor, Claude Code, or any other): do not answer
+this CLI's interactive prompts. Run it non-interactively instead \u2014 one command, no
+prompts, no keystrokes to drive:
+
+  # Inside an existing project (package.json present) \u2014 embedded flow
+  npx --yes @pega/sdk init --ai-tool <${AI_TOOL_CHOICES}>
+
+  # In an empty folder \u2014 new project
+  npx --yes @pega/sdk init --name <project-name> --framework <${FRAMEWORK_CHOICES}> --ai-tool <${AI_TOOL_CHOICES}>
+
+Mode is auto-detected from whether package.json exists in the current folder \u2014 you
+do not need to pass --mode.
+
+--ai-tool is you, the agent running this command \u2014 not something to detect or ask
+about. GitHub Copilot -> copilot, Cursor -> cursor, Claude Code -> claude-code.
+Always pass it: it decides which agent config files get written, and a repo can
+contain another assistant's config left behind by someone else.
+`.trim();
 var HELP_TEXT = `
-Usage: npx @pega/sdk init [flags]
+Usage: npx --yes @pega/sdk init [flags]
 
-Run with no flags for the interactive setup. Pass any flag below (or --json)
-to scaffold non-interactively in one shot \u2014 no prompts are shown.
+Scaffolds a Pega SDK application. Run with no flags for the interactive setup,
+or pass any flag below to scaffold non-interactively in one shot.
+
+Mode is auto-detected from the folder you run in: an empty folder creates a new
+project, a folder that already has a package.json integrates the embedded flow.
 
 Common:
-  --json <path|->        Answers file (JSON), matching the shapes documented in
-                          README.md. Use "-" to read from stdin. Values here win
-                          over the individual flags below when both are given.
-  --mode <new|embedded>   Override auto-detection of new-project vs embedded.
-  --ai-tool <tool>        copilot | cursor | claude-code (embedded: required; new: also accepts "none")
-  --help                  Show this help.
+  --mode <new|embedded>   Override the auto-detection described above.
+  --ai-tool <tool>        ${AI_TOOLS.join(" | ")} (new: also accepts "none").
+                          Adds that assistant's config and skill files.
+  --yes                   Accept all defaults; enough on its own to skip every prompt.
+  --help, -h              Show this help.
 
 New project:
   --name <name>           Project directory name (required).
-  --framework <fw>        react | angular | web-components | react-native (required).
+  --framework <fw>        ${FRAMEWORKS.join(" | ")}. Default: react.
   --templates <bool>      Include starter components. Default: true.
   --categories <list>     Comma-separated: fields,templates,widgets,infra,designSystemExtension.
                           Default: all categories when --templates is true.
@@ -1274,20 +1281,17 @@ New project:
 Embedded:
   --conflict-policy <p>   merge | override. Default: merge.
 
-Optional, either mode (CI/scripted use only \u2014 a chat agent should not ask a
-user for these; they're configured post-scaffold by editing sdk-config.json /
-the generated MCP config file):
-  --server-url <url>
-  --app-alias <alias>
-  --client-id <id>
-  --mcp-rule-name <name>
-  --mcp-rule-ins-key <key>
-
 Examples:
-  npx @pega/sdk init --name my-app --framework react --ai-tool copilot --templates false --yes
-  npx @pega/sdk init --mode embedded --ai-tool copilot --conflict-policy merge
-  npx @pega/sdk init --json ./sdk-answers.json
+  npx --yes @pega/sdk init --name my-app --framework react --ai-tool copilot --templates false
+  npx --yes @pega/sdk init --mode embedded --ai-tool cursor --conflict-policy merge
+
+------------------------------------------------------------------------------
+${AGENT_QUICKSTART}
 `.trim();
+var HELP_FLAGS = /* @__PURE__ */ new Set(["--help", "-h", "-help", "--h", "-?"]);
+function isHelpRequest(argv) {
+  return argv[0] === "help" || argv.some((arg) => HELP_FLAGS.has(arg));
+}
 function parseCliArgs(argv) {
   let values;
   try {
@@ -1295,17 +1299,11 @@ function parseCliArgs(argv) {
       args: argv,
       options: {
         help: { type: "boolean" },
-        json: { type: "string" },
         yes: { type: "boolean" },
         mode: { type: "string" },
         name: { type: "string" },
         framework: { type: "string" },
         "ai-tool": { type: "string" },
-        "server-url": { type: "string" },
-        "app-alias": { type: "string" },
-        "client-id": { type: "string" },
-        "mcp-rule-name": { type: "string" },
-        "mcp-rule-ins-key": { type: "string" },
         templates: { type: "string" },
         categories: { type: "string" },
         "conflict-policy": { type: "string" }
@@ -1318,17 +1316,11 @@ function parseCliArgs(argv) {
   }
   return {
     help: Boolean(values.help),
-    json: values.json,
     yes: Boolean(values.yes),
     mode: values.mode,
     name: values.name,
     framework: values.framework,
     aiTool: values["ai-tool"],
-    serverUrl: values["server-url"],
-    appAlias: values["app-alias"],
-    clientId: values["client-id"],
-    mcpRuleName: values["mcp-rule-name"],
-    mcpRuleInsKey: values["mcp-rule-ins-key"],
     templates: values.templates,
     categories: values.categories,
     conflictPolicy: values["conflict-policy"]
@@ -1336,23 +1328,13 @@ function parseCliArgs(argv) {
 }
 function isNonInteractive(args) {
   return Boolean(
-    args.help || args.json || args.mode || args.name || args.framework || args.aiTool || args.serverUrl || args.appAlias || args.clientId || args.mcpRuleName || args.mcpRuleInsKey || args.templates || args.categories || args.conflictPolicy || args.yes
+    args.help || args.mode || args.name || args.framework || args.aiTool || args.templates || args.categories || args.conflictPolicy || args.yes
   );
 }
-function readJsonAnswers(source) {
-  const raw = source === "-" ? fs3.readFileSync(0, "utf-8") : fs3.readFileSync(path3.resolve(source), "utf-8");
-  try {
-    return JSON.parse(raw);
-  } catch {
-    throw new CliValidationError(`--json source "${source}" is not valid JSON.`);
-  }
-}
-function pickFrom(answers, key, flagValue) {
-  return answers[key] ?? flagValue;
-}
 function assertFramework(value) {
+  if (value === void 0) return "react";
   if (typeof value === "string" && FRAMEWORKS.includes(value)) return value;
-  throw new CliValidationError(`--framework is required and must be one of: ${FRAMEWORKS.join(", ")}`);
+  throw new CliValidationError(`--framework must be one of: ${FRAMEWORKS.join(", ")}`);
 }
 function parseAiTool(value) {
   if (value === void 0 || value === "none") return null;
@@ -1362,8 +1344,19 @@ function parseAiTool(value) {
 function parseRequiredAiTool(value) {
   if (typeof value === "string" && AI_TOOLS.includes(value)) return value;
   throw new CliValidationError(
-    `--ai-tool is required for the embedded flow and must be one of: ${AI_TOOLS.join(", ")}`
+    `--ai-tool must be one of: ${AI_TOOLS.join(", ")}. Pass the assistant you are running as.`
+  );
+}
+var AI_TOOL_MARKERS = {
+  copilot: [".github/copilot-instructions.md", ".github/instructions", ".github/prompts", ".github/skills"],
+  cursor: [".cursor", ".cursorrules"],
+  "claude-code": [".claude", "CLAUDE.md"]
+};
+function detectRepoAiTool(cwd) {
+  const matches = Object.keys(AI_TOOL_MARKERS).filter(
+    (tool) => AI_TOOL_MARKERS[tool].some((marker) => fs3.existsSync(path3.join(cwd, marker)))
   );
+  return matches.length === 1 ? matches[0] : void 0;
 }
 function parseBoolean(value, fallback) {
   if (value === void 0) return fallback;
@@ -1384,36 +1377,36 @@ function parseCategories(value) {
   return entries;
 }
 function resolveNonInteractiveUserChoices(args) {
-  const answers = args.json ? readJsonAnswers(args.json) : {};
-  const projectName = pickFrom(answers, "projectName", args.name);
+  const projectName = args.name;
   if (typeof projectName !== "string" || !projectName) {
-    throw new CliValidationError('Project name is required (--name, or "projectName" in --json).');
+    throw new CliValidationError("Project name is required (--name).");
   }
   if (!PROJECT_NAME_RE.test(projectName)) {
     throw new CliValidationError("Invalid project name. Use lowercase letters, numbers, hyphens, and dots.");
   }
-  const framework = assertFramework(pickFrom(answers, "framework", args.framework));
-  const aiTool = parseAiTool(pickFrom(answers, "aiTool", args.aiTool));
+  const framework = assertFramework(args.framework);
+  const aiTool = parseAiTool(args.aiTool);
   const isReactNative = framework === "react-native";
-  const includeTemplates = isReactNative ? true : parseBoolean(pickFrom(answers, "includeTemplates", args.templates), true);
-  const componentCategories = isReactNative ? ["fields", "templates", "infra"] : includeTemplates ? parseCategories(pickFrom(answers, "componentCategories", args.categories)) : [];
+  const includeTemplates = isReactNative ? true : parseBoolean(args.templates, true);
+  const componentCategories = isReactNative ? ["fields", "templates", "infra"] : includeTemplates ? parseCategories(args.categories) : [];
   return {
     projectName,
     framework,
     aiTool,
     includeTemplates,
-    componentCategories,
-    serverUrl: pickFrom(answers, "serverUrl", args.serverUrl),
-    appAlias: pickFrom(answers, "appAlias", args.appAlias),
-    clientId: pickFrom(answers, "clientId", args.clientId),
-    mcpRuleName: pickFrom(answers, "mcpRuleName", args.mcpRuleName),
-    mcpRuleInsKey: pickFrom(answers, "mcpRuleInsKey", args.mcpRuleInsKey)
+    componentCategories
   };
 }
-function resolveNonInteractiveEmbeddedChoices(args) {
-  const answers = args.json ? readJsonAnswers(args.json) : {};
-  const aiTool = parseRequiredAiTool(pickFrom(answers, "aiTool", args.aiTool));
-  const conflictPolicyRaw = pickFrom(answers, "conflictPolicy", args.conflictPolicy);
+function resolveNonInteractiveEmbeddedChoices(args, cwd) {
+  const requestedAiTool = args.aiTool;
+  const inferredAiTool = requestedAiTool === void 0 ? detectRepoAiTool(cwd) : void 0;
+  if (inferredAiTool) {
+    console.warn(
+      `Warning: --ai-tool was not passed; guessed "${inferredAiTool}" from this repo's existing config. If you are a different assistant, re-run with --ai-tool set to yourself.`
+    );
+  }
+  const aiTool = parseRequiredAiTool(requestedAiTool ?? inferredAiTool);
+  const conflictPolicyRaw = args.conflictPolicy;
   let conflictPolicy;
   if (conflictPolicyRaw !== void 0) {
     if (conflictPolicyRaw !== "merge" && conflictPolicyRaw !== "override") {
@@ -1423,11 +1416,6 @@ function resolveNonInteractiveEmbeddedChoices(args) {
   }
   return {
     aiTool,
-    serverUrl: pickFrom(answers, "serverUrl", args.serverUrl),
-    appAlias: pickFrom(answers, "appAlias", args.appAlias),
-    clientId: pickFrom(answers, "clientId", args.clientId),
-    mcpRuleName: pickFrom(answers, "mcpRuleName", args.mcpRuleName),
-    mcpRuleInsKey: pickFrom(answers, "mcpRuleInsKey", args.mcpRuleInsKey),
     conflictPolicy
   };
 }
@@ -1435,16 +1423,11 @@ function resolveNonInteractiveEmbeddedChoices(args) {
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version: sdkVersion } = require2("../package.json");
-async function runNonInteractive(cwd, rawArgs) {
-  const flags = parseCliArgs(rawArgs);
-  if (flags.help) {
-    console.log(HELP_TEXT);
-    return;
-  }
+async function runNonInteractive(cwd, flags) {
   try {
     const mode = flags.mode ?? (detectExistingProject(cwd) ? "embedded" : "new");
     if (mode === "embedded") {
-      const choices = resolveNonInteractiveEmbeddedChoices(flags);
+      const choices = resolveNonInteractiveEmbeddedChoices(flags, cwd);
       const conflicts = collectEmbeddedConflicts(cwd, choices);
       if (conflicts.length > 0) {
         console.log(
@@ -1463,22 +1446,40 @@ async function runNonInteractive(cwd, rawArgs) {
     }
   } catch (err) {
     console.error(pc.red(err instanceof CliValidationError || err instanceof Error ? err.message : String(err)));
+    console.error(`
+${AGENT_QUICKSTART}
+
+Full flag reference: npx --yes @pega/sdk init --help`);
     process.exit(1);
   }
 }
 async function main() {
   const args = process.argv.slice(2);
+  if (isHelpRequest(args)) {
+    console.log(HELP_TEXT);
+    return;
+  }
   const command = args[0];
   if (command !== "init") {
     console.error(`Unknown command "${command ?? ""}".
-
-Usage: npx @pega/sdk init`);
+`);
+    console.error(HELP_TEXT);
     process.exit(1);
   }
   const cwd = process.cwd();
   const rest = args.slice(1);
-  if (isNonInteractive(parseCliArgs(rest))) {
-    await runNonInteractive(cwd, rest);
+  let flags;
+  try {
+    flags = parseCliArgs(rest);
+  } catch (err) {
+    console.error(pc.red(err instanceof Error ? err.message : String(err)));
+    console.error(`
+${HELP_TEXT}`);
+    process.exit(1);
+    return;
+  }
+  if (isNonInteractive(flags)) {
+    await runNonInteractive(cwd, flags);
     return;
   }
   console.clear();
@@ -1631,11 +1632,6 @@ Usage: 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?",
@@ -1770,12 +1766,7 @@ Usage: npx @pega/sdk init`);
     framework,
     aiTool,
     includeTemplates,
-    componentCategories,
-    serverUrl,
-    appAlias,
-    clientId,
-    mcpRuleName,
-    mcpRuleInsKey
+    componentCategories
   };
   const spinner2 = p.spinner();
   spinner2.start("Scaffolding your project\u2026");

package/package.json

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

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

@@ -55,7 +55,7 @@ Determine which workflow governs the request, then execute it by reading the ref
 
 ### Step 0.0 — Ensure the Pega server connection is configured
 
-Before executing any data source below, read and execute `{{SKILL_DIR}}/connect-pega-server.md`. It is a no-op when the connection is already configured, and otherwise gathers the missing values from the user and writes them into the MCP config and `sdk-config.json` before this step continues.
+Before executing any data source below, read and execute `{{SKILL_DIR}}/connect-pega-server.md`. It is a no-op when the connection is already configured. Otherwise, it resolves existing values from the active MCP config, browser-served `sdk-config.json`, and environment files, then asks once for every missing non-secret value. The user may provide those values in chat or write them into any allowed configuration file named by the gate; the assistant re-reads the files and synchronizes every applicable destination. The gate may pause for an environment-sourced Pega MCP client secret (Cursor only) or an MCP reconnect. After the user retries, rerun the gate before executing any data source.
 
 ### Step 0.1 — Check for a case type in the prompt
 
@@ -65,11 +65,11 @@ Scan the user's message for a **Pega case type class name** (hyphen-separated se
 
 Execute the data source **`D_pzGetCaseTypesInApp`**, which returns the case types 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.
+Execute it directly, by name. An execution tool may instruct you to look up the available data pages before calling it; you may run that lookup to satisfy the tool, but **its output is not authoritative**. The advertised list omits platform data pages that execute perfectly well, so a data page missing from it is not evidence that it is unavailable — and never a reason to stop, to ask the user to expose it through the MCP rule, or to abandon the flow. Only a failed execution attempt counts as a failure. 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 a hardcoded component list.
 
-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.
+If the execution runs but fails, report the failure and the error the server returned. You may list the server's advertised data sources alongside it as context, but never present that list as evidence the data page is unavailable. Do not substitute a different data page.
 
 1. Check `applicationIsConstellationCompatible` in the response. If it is `false`, stop and tell the user the application is not Constellation-compatible and cannot be embedded.
 2. If the user's message did NOT contain a case type class name, present the returned case types as a numbered pick-list of `name — ID` pairs and ask which one to embed.
@@ -81,7 +81,7 @@ If the execution runs but fails, report the failure, and if the server's data so
 
 Execute the data source **`D_pyCaseViewComponentsByType`** for the confirmed case type. Pass the name exactly as written — like the data page above, it is part of the platform. It returns the components the case type uses, each mapped to the views it appears in.
 
-Pass the confirmed case type **ID** — the fully qualified class name, not the display label. Supply only the parameters the execution tool declares, taking their names from the tool itself; do not add parameters it does not declare, and do not invent values for ones you cannot resolve.
+Pass the confirmed case type **ID** — the fully qualified class name, not the display label — as the **`CaseType`** parameter. That is the only parameter this data page takes: do not add others, and do not invent values for ones you cannot resolve.
 
 Reduce that response to a generatable list by applying the following in order. Points 2 and 3 are independent rules that remove components for unrelated reasons — keep those reasons distinct when reporting the outcome rather than presenting one merged list of removals.
 
@@ -127,13 +127,13 @@ Step 0 of the wire-integration skill resolves both, checks whether the named con
 
 If the user named a launch point but no render target, the skill infers it from what the control already does. If they named neither, the skill asks using surfaces drawn from the customer's own application. Never assume either one.
 
-| Workflow           | Required inputs                                                                                   |
-| ------------------ | ------------------------------------------------------------------------------------------------- |
-| Analyze            | Case type class + access to the customer's codebase                                               |
-| Generate           | Case type class + component list + Design Profile (or permission to create one)                   |
-| Full embedded flow | Case type class + server-resolved component list + codebase access + launch point + render target |
-| Wire integration   | Case type class + generated `pega-components/` folder must exist + launch point + render target   |
-| Verify integration | A wired integration + a human available to authenticate when the flow reaches the Pega login form |
+| Workflow           | Required inputs                                                                                                             |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
+| Analyze            | Case type class + access to the customer's codebase                                                                         |
+| Generate           | Case type class + component list + Design Profile (or permission to create one)                                             |
+| Full embedded flow | Case type class + server-resolved component list + codebase access + launch point + render target                           |
+| Wire integration   | Case type class + generated components folder (location resolved during analysis) must exist + launch point + render target |
+| Verify integration | A wired integration + a human available to authenticate when the flow reaches the Pega login form                           |
 
 ---
 
@@ -143,7 +143,7 @@ If the user named a launch point but no render target, the skill infers it from
 2. **Always read before executing** — read the skill or prompt file fully before acting on it. Never paraphrase from memory.
 3. **Follow steps in order** — each skill/prompt defines numbered steps. Execute them sequentially without skipping.
 4. **Design Profile is the bridge** — the analysis skill produces it, the generation prompt consumes it. If generation is requested and no profile exists, analysis must run first. Step 0 of the wiring skill consumes it too, when it has to ask where the flow should render — which is why analysis precedes that gate rather than following it.
-5. **Never modify the customer's existing code** except at the seams that the wiring and verification skills enumerate. The `pega-components/` folder is purely additive, and a failing verification check is never permission to edit customer code outside those seams to make it pass.
+5. **Never modify the customer's existing code** except at the seams that the wiring and verification skills enumerate. The generated components folder (location resolved during analysis and recorded in the Design Profile) is purely additive, and a failing verification check is never permission to edit customer code outside those seams to make it pass.
 6. **Component skills are authoritative** — the behavioral contracts in `{{SKILL_DIR}}/field-skills/`, `template-skills/`, `widget-skills/`, `design-system-extension-skills/`, and `infra-skills/` define what each component must do. These are non-negotiable.
 7. **Adapt to the customer's framework** — the skills and prompts are framework-agnostic. Determine the customer's framework from their project configuration and apply conventions accordingly.
 8. **Verification is mandatory, and it is not only static** — the generation prompt's checks confirm the generated files are well-formed. They do not confirm the flow runs. Whenever the integration has been wired, finish with `{{SKILL_DIR}}/embedded-flow/run-and-verify-integration.md` and report how far it got. Never declare success on static checks alone.
@@ -157,7 +157,7 @@ If the user named a launch point but no render target, the skill infers it from
 | Situation                                                        | Response                                                                                                                                                                                                                                                                                                                                       |
 | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | A Pega data source cannot be executed in this session            | Stop. Report that the Pega MCP server is not available to this conversation — either it is not running, or it was started after the conversation began and its tools are not bound to this session, which a new session fixes. Do not name a configuration file, a path, or a server label, and do not fall back to a hardcoded component list |
-| A required data page is not among the data sources offered       | Report which data sources the server did offer, then stop. Do not substitute a different data page and do not fall back to a hardcoded list                                                                                                                                                                                                    |
+| A required data page is not among the data sources offered       | Not a failure state. The advertised list omits platform data pages that execute correctly — execute it by name anyway. Only an actual execution error is a failure, and only then report what the server offered                                                                                                                               |
 | `D_pzGetCaseTypesInApp` returns no case types                    | The operator has no creatable case types. Ask the user to verify the application alias and the operator's permissions                                                                                                                                                                                                                          |
 | `D_pyCaseViewComponentsByType` returns no components             | Report the case type that was queried and ask the user to confirm it has views configured in its lifecycle. Do not fall back to a hardcoded list                                                                                                                                                                                               |
 | The starting-fields capability is unavailable or returns nothing | Record that no property names were confirmed and continue. The wiring step seeds nothing and reports the gap — it must not infer names from the customer's domain model                                                                                                                                                                        |

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

@@ -47,7 +47,7 @@ Pega SDK packages (`.tgz` files) have been added to the project root and referen
 
 ### SDK Configuration
 
-`sdk-config.json` contains connection details for the Pega server. The AI assistant gathers the server URL, app alias, OAuth client ID, and (when the MCP configuration requires one) a client secret from the user in chat the first time a workflow needs them, and fills them in automatically — see `{{SKILL_DIR}}/connect-pega-server.md`. The case type is resolved from the server during the embedded flow itself.
+The browser-served `sdk-config.json` contains non-secret Pega server connection details. The first workflow that needs a live server runs `{{SKILL_DIR}}/connect-pega-server.md`, which resolves values from the active SDK config, MCP config, and environment files, then asks once for all missing non-secret values. The user may provide those values in chat or update an allowed file; the assistant synchronizes every applicable destination. Only a Cursor-style MCP entry requires a Pega MCP client secret, which must come from a private environment variable and is never requested in chat or written to `sdk-config.json`. The browser SDK's OAuth grant configuration remains the user's choice. The case type is resolved from the server during the embedded flow itself.
 
 ---
 
@@ -100,7 +100,7 @@ Most infrastructure components ship from the SDK and are never generated. Three
 
 ## 5. Rules
 
-1. **Never modify the customer's existing components during analysis or generation** — the `pega-components/` folder is additive. Wiring is the exception: it edits the integration seams listed in the wire-integration skill, plus the verification tooling seams listed in the run-and-verify-integration skill. A failing verification check never widens that set
+1. **Never modify the customer's existing components during analysis or generation** — the generated components folder (location resolved during analysis and recorded in the Design Profile) is additive. Wiring is the exception: it edits the integration seams listed in the wire-integration skill, plus the verification tooling seams listed in the run-and-verify-integration skill. A failing verification check never widens that set
 2. **Match the customer's conventions** — generated code should look like the customer wrote it
 3. **Satisfy the Pega behavioral contract** — every component must implement what its skill file requires
 4. **Use the customer's design system** — never introduce a new UI library

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

@@ -8,6 +8,10 @@ You are assisting developers in a reference application that demonstrates the Pe
 
 This is a **reference implementation** — not a framework. The UI components (fields, templates, widgets) are intentionally simple sample implementations meant to be swapped out. The SDK wiring (bootstrap, PConnect bridge, component registry) is reusable infrastructure that should NOT be modified.
 
+### SDK Configuration
+
+`sdk-config.json` and the generated MCP config file are scaffolded blank/placeholder — connection details are never collected at scaffold time. The first workflow that needs a live Pega server runs `{{SKILL_DIR}}/connect-pega-server.md`, which resolves values from the active SDK config, MCP config, and environment files, then asks once for all missing non-secret values. The user may provide those values in chat or update an allowed file; the assistant synchronizes every applicable destination. A Pega MCP client secret is required only when the active MCP entry has `auth.clientSecret` (currently Cursor), must come from a private environment variable, and is never requested in chat or written to browser-served SDK configuration.
+
 ---
 
 ## 2. What Is Replaceable vs. Infrastructure

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

@@ -1,5 +1,5 @@
 ---
-ai-globs: **/designSystemExtension/**/*
+ai-globs: **/{AlertBanner,Banner,CaseSummaryFields,DetailsFields,FieldGroup,FieldGroupList,FieldValueList,Operator,Pulse,RichTextEditor,WssQuickCreate}/**/*
 ---
 
 # Design System Extension Component Rules

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

@@ -10,7 +10,7 @@ When generating or modifying Pega components in the `pega-components/` folder (c
 
 ## Context
 
-These components are different from the reference app's sample components. They are generated to live **inside a customer's existing project**, using the customer's design system so that they are visually indistinguishable from the rest of their UI. The Design Profile (`.design-profile.md`) in the same folder describes the customer's visual conventions.
+These components are different from the reference app's sample components. They are generated to live **inside a customer's existing project**, using the customer's design system so that they are visually indistinguishable from the rest of their UI. The Design Profile (`docs/design-profile.md` at the project root) describes the customer's visual conventions.
 
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-ai-globs: **/field/**/*
+ai-globs: **/{AutoComplete,CancelAlert,Checkbox,Currency,Date,DateTime,Decimal,Dropdown,Email,Group,Integer,Location,Multiselect,ObjectReference,Percentage,Phone,RadioButtons,RichText,ScalarList,SelectableCard,SemanticLink,TextArea,TextContent,TextInput,Time,URL,UserReference}/**/*
 ---
 
 # Field Component Rules

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

@@ -1,5 +1,5 @@
 ---
-ai-globs: **/infra/**/*
+ai-globs: **/{ActionButtons,DashboardFilter,DeferLoad,MultiStep,NavBar,Stages,VerticalTabs}/**/*
 ---
 
 # Infrastructure (Chrome) Component Rules

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

@@ -1,5 +1,5 @@
 ---
-ai-globs: **/template/**/*
+ai-globs: **/{AdvancedSearch,AppShell,BannerPage,CaseSummary,CaseView,CaseViewActionsMenu,Confirmation,DataReference,DefaultForm,DefaultPage,Details,FieldGroupTemplate,HierarchicalForm,InlineDashboard,InlineDashboardPage,ListPage,ListView,MultiReferenceReadOnly,NarrowWide,ObjectPage,OneColumn,PromotedFilters,SelfServiceCaseView,SimpleTable,SingleReferenceReadOnly,SubTabs,TwoColumn,WideNarrow,WssNavBar,SearchForm,SearchGroups}/**/*
 ---
 
 # Template Component Rules

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

@@ -1,5 +1,5 @@
 ---
-ai-globs: **/widget/**/*
+ai-globs: **/{AppAnnouncement,Attachment,CaseHistory,FileUtility,Followers,QuickCreate,SummaryItem,SummaryList,ToDo,ActionButtonsForFileUtil}/**/*
 ---
 
 # Widget Component Rules

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

@@ -105,7 +105,7 @@ Record the visual treatment only. Generated components read validation messages
 
 ### 4. File Conventions
 
-**Context only.** Generated components use Pega-owned paths and names (`pega-components/{type}/{ComponentName}/`), so Structure and Naming below do not apply to them. Re-exports, test location, and style location still inform co-located files.
+**Context only.** Generated components use Pega-owned paths and names (`{output_path}/{ComponentName}/`), so Structure and Naming below do not apply to them. Re-exports, test location, and style location still inform co-located files.
 
 | Field          | Description                                             |
 | -------------- | ------------------------------------------------------- |
@@ -126,7 +126,7 @@ Record the visual treatment only. Generated components read validation messages
 | Default/named preference | Which import style dominates                                     |
 | Style imports            | How stylesheets or style modules are imported                    |
 
-Generated components import the customer's UI primitives through their path aliases. Relative paths are used only _within_ `pega-components/` — for shared helpers, barrel files, and the registry file's component imports. One Pega component is never imported into another to render it; that always goes through the component registry.
+Generated components import the customer's UI primitives through their path aliases. Relative paths are used only _within_ the generated output folder (`{output_path}`) — for shared helpers, barrel files, and the registry file's component imports. One Pega component is never imported into another to render it; that always goes through the component registry.
 
 ---
 

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

@@ -57,17 +57,17 @@ Once design system, base folder, and type scope are resolved, continue to Step 0
 
 ### 0.5.0 — Ensure the Pega server connection is configured
 
-Before executing any data source below, read and execute `{{SKILL_DIR}}/connect-pega-server.md`. It is a no-op when the connection is already configured, and otherwise gathers the missing values from the user and writes them into the MCP config and `sdk-config.json` before this step continues.
+Before executing any data source below, read and execute `{{SKILL_DIR}}/connect-pega-server.md`. It is a no-op when the connection is already configured. Otherwise, it resolves existing values from the active MCP config, application `sdk-config.json`, and environment files; asks once for every missing non-secret value; and writes chat-provided values to every applicable file. It may pause for an environment-sourced Pega MCP client secret (Cursor only) or an MCP reconnect. After the user retries, rerun the gate before executing any data source.
 
 ### 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.
+Execute it directly, by name. An execution tool may instruct you to look up the available data pages before calling it; you may run that lookup to satisfy the tool, but **its output is not authoritative**. The advertised list omits platform data pages that execute perfectly well, so a data page missing from it is not evidence that it is unavailable — and never a reason to stop, to ask the user to expose it through the MCP rule, or to abandon the flow. Only a failed execution attempt counts as a failure. 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.
+If the execution runs but fails, report the failure and the error the server returned. You may list the server's advertised data sources alongside it as context, but never present that list as evidence the data page is unavailable. Do not substitute a different data page.
 
 The response's `pxResults` array holds one entry per portal. Then:
 
@@ -88,6 +88,8 @@ Ask the user which parts of the portal to convert: **Landing pages**, **Cases**,
 
 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`.
 
+Execute it — and every data page this step dispatches to — by name. Step 0.5.1's rule still applies: absence from an availability lookup is not evidence a data page is unavailable, and never a reason to stop.
+
 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.
@@ -115,17 +117,59 @@ Do not supply `ApplicationName` or `ApplicationVersion` to `D_pyLandingPageCompo
 
 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`.
 
+Execute it — and `D_pyCaseViewComponentsByType` below — by name. Step 0.5.1's rule still applies: absence from an availability lookup is not evidence a data page is unavailable, and never a reason to stop.
+
 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
+### 0.5.5 — Resolve names, present, and ask which components to generate
 
 Union whatever Step 0.5.3 and Step 0.5.4 produced (only one ran unless the user chose Both) and drop duplicates across the two.
 
-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.
+Every component you generate must correspond to one canonical component listed in `{{PROMPT_DIR}}/component-manifest.json`. Pega defines a fixed set of components, and the manifest is the complete list of them. Read it once. It contains three things you need here:
+
+- `components` — the canonical names, grouped by type (`field`, `template`, `widget`, `designSystemExtension`, `infra`)
+- `aliases` — known non-canonical names and the canonical name each one maps to
+- `behaviorClasses` — a fixed list of behaviour descriptions, each mapping to one or more canonical names
+
+For each name the server returned, work through the following stages in order. Stop at the first stage that produces an answer. These names come from Pega's own view metadata, so most are already canonical and settle at Stage 1 — the later stages exist for the ones that do not.
+
+#### Stage 1 — Normalized name match
+
+1. Take the returned name and make a normalized form: convert it to lowercase, then remove all spaces, hyphens, and underscores, then remove a trailing `field`, `component`, `input`, or `control` if one is present.
+2. Build the same normalized form for every canonical name in `components`.
+3. If exactly one canonical name has the same normalized form, that is the answer.
+
+#### Stage 2 — Alias lookup
+
+1. Look up the returned name in the `aliases` object. Compare using the normalized form from Stage 1 so that casing and spacing do not matter.
+2. If the name is present, the value it maps to is the answer.
+
+#### Stage 3 — Behaviour class match
+
+Do not search for a "similar sounding" name here. Follow these three sub-steps exactly.
+
+1. Decide what the component does for the end user, and choose **exactly one** entry from the `behaviorClasses` list that describes that behaviour. You must pick one of the listed classes. If you cannot honestly place the component in any of them, go to Stage 4.
+2. Read the canonical names that class maps to. If the class maps to exactly one name, that is the candidate.
+3. Read the candidate's skill file — `{{SKILL_DIR}}/{type}-skills/<CanonicalName>.md`, where `{type}` is `field`, `template`, `widget`, `design-system-extension`, or `infra` — and confirm its behavioural contract covers what the component does. If it clearly does not, go to Stage 4.
+
+If the class maps to more than one canonical name, choose between them using the page or case type the name came from and the surrounding context. If the context does not make the choice obvious, go to Stage 4.
+
+#### Stage 4 — Ask the user
+
+Tell the user the name could not be resolved to a Pega component, list the two or three canonical names you considered most likely, and ask which one they want — or whether to leave it out. Do not guess, and do not proceed with that component until they answer. Collect every unresolved name into a **single** question rather than asking once per name; a portal can return a long list, and one question per name is not a usable gate.
+
+#### Rules for this step
+
+- This process always ends in one of two ways: a single canonical name, or a question to the user. It never ends with you inventing a component.
+- Once a canonical name is chosen, use it everywhere afterwards: the type grouping, the skill file you read, the generated folder name, and the registry key. The name the server returned is only used when reporting the substitution back to the user.
+- Record the pairing of returned name and canonical name. You will report it in the Step 9 summary.
+- If two different returned names resolve to the same canonical name, generate that component once.
+
+Group the resolved canonical names by type — `field`, `template`, `widget`, `designSystemExtension`, or `infra`.
 
 Present the grouped list — noting, for any component contributed by more than one page or case type, which ones — and ask which components to generate as a **checkbox list**, offering selecting all of them as an explicit option. Where a returned component is one the SDK provides and this prompt never generates — anything named in Step 8's never-generate list, or a structural wrapper such as `View`, `Region`, or `FlowContainer` — keep it visible in the list but mark it as not generatable and say why, so the user can see it's used without expecting a folder for it.
 
@@ -544,3 +588,4 @@ Report a final summary:
 - `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, or because they are SDK-provided infrastructure)
+- Any name the server returned that resolved to a **different** canonical name, with the stage that produced the match (normalized name, alias, behaviour class, or the user's choice). Say it in your reply as well — the user must never discover a substitution only by reading the generated files

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

@@ -1,5 +1,5 @@
 ---
-ai-description: "Generate Pega components styled to match a customer's existing application — given a component list and a Design Profile, produces a pega-components/ folder with implementations that satisfy the Pega behavioral contract while rendering with the customer's design system, tokens, and styling approach, and reading like their own code"
+ai-description: "Generate Pega components styled to match a customer's existing application — given a component list and a Design Profile, produces a generated components folder (location chosen by the user during analysis) with implementations that satisfy the Pega behavioral contract while rendering with the customer's design system, tokens, and styling approach, and reading like their own code"
 ---
 
 ## Step 0 — Resolve missing information
@@ -7,8 +7,8 @@ ai-description: "Generate Pega components styled to match a customer's existing
 Read the user's message carefully. Extract:
 
 - **Component list** — the Pega component names to generate (e.g., `TextInput`, `Dropdown`, `DefaultForm`, `TwoColumn`, `ToDo`)
-- **Design Profile location** — the path to the `.design-profile.md` file (default: `pega-components/.design-profile.md`)
-- **Output path** — where to write the generated components (default: `pega-components/`)
+- **Design Profile location** — always `docs/design-profile.md` at the project root. This location is fixed and never moves with the output path
+- **Output path** — read the **Output Path** field from Section 1 of the Design Profile and use it verbatim as `{output_path}`. Never re-ask for it and never fall back to a hardcoded default — it was already resolved once, with the user, during analysis
 
 The **component list** is required. If it is not provided and cannot be inferred from prior conversation context, stop and ask the user.
 
@@ -77,7 +77,7 @@ After every name is resolved, group the canonical names by type so you can read
 
 Read the following **once** before the generation loop:
 
-1. **The Design Profile** — read the full `.design-profile.md`. Its design tokens, styling convention, and validation display convention are authoritative and must be replicated. Its component patterns (input interface, state management, event handling) and file conventions describe the customer's own code — read them for context, but generated components follow the Pega contract and Pega-owned paths instead.
+1. **The Design Profile** — read the full `docs/design-profile.md`. Its design tokens, styling convention, and validation display convention are authoritative and must be replicated. Its component patterns (input interface, state management, event handling) and file conventions describe the customer's own code — read them for context, but generated components follow the Pega contract and Pega-owned paths instead.
 
 2. **General type-level skills** — for each component type present in the grouped list, read the corresponding general skill:
 
@@ -161,17 +161,16 @@ Create the component implementation that satisfies **both**:
 
 State, events, validation wiring, and prop contracts are deliberately absent from that list — they come from the Pega behavioral contract above, no matter how the customer writes their own forms. A customer whose own screens use a form library does not change how a generated component holds a value or commits it.
 
-**Exception — the output path is not the customer's to choose.** `pega-components/` is a generated, Pega-owned tree that the customer never authors in, so its layout is fixed rather than inferred from the Design Profile. Write the component to:
+**Exception — the layout beneath `{output_path}` is not the customer's to choose.** The folder the user resolved during analysis is a generated, Pega-owned tree that the customer never authors in, so what goes underneath it is fixed rather than inferred from the Design Profile. Write the component to:
 
 ```
-{output_path}/{type}/{ComponentName}/{ComponentName}.{ext}
+{output_path}/{ComponentName}/{ComponentName}.{ext}
 ```
 
-- `{type}` is literal — `field`, `template`, `widget`, `designSystemExtension`, or `infra` — and is never renamed or flattened. The instruction globs match on it.
-- `{ComponentName}` is the canonical Pega component name resolved in Step 1, verbatim, for both the folder and the implementation file, whatever the customer's naming style is. `Checkbox` produces `Checkbox/Checkbox.*`, never `checkbox/CheckboxField.*`; `Date` produces `Date/Date.*`, never `date/DateField.*`.
+- `{ComponentName}` is the canonical Pega component name resolved in Step 1, verbatim, for both the folder and the implementation file, whatever the customer's naming style is. `Checkbox` produces `Checkbox/Checkbox.*`, never `checkbox/CheckboxField.*`; `Date` produces `Date/Date.*`, never `date/DateField.*`. Components are never grouped into a further `field`/`template`/`widget`/`designSystemExtension`/`infra` subfolder — every component's own folder sits directly under `{output_path}`.
 - `{ext}` follows the customer's framework, not their file-naming style.
 
-Deterministic paths are what let tooling, globs, and regeneration find components again. Customer conventions govern the _contents_ of these files, not their location or name. If the customer's repo lints file names, exclude `pega-components/` from that rule rather than bending the paths.
+Deterministic paths are what let tooling and regeneration find components again. Customer conventions govern the _contents_ of these files, not their location or name. If the customer's repo lints file names, exclude `{output_path}` from that rule rather than bending the paths.
 
 ### 4d. Register the component
 
@@ -277,7 +276,7 @@ Read the generated registry file and confirm:
 Verify that every import in the generated files resolves to either:
 
 - A package present in the customer's dependency manifest
-- A file within the generated `pega-components/` folder
+- A file within the generated components folder (`{output_path}`)
 - The Pega SDK packages (added in integration wiring)
 
 If any import references a package not in the project, either:
@@ -304,7 +303,7 @@ Whenever `Requested Name` and `Resolved As` differ, say so in your reply as well
 
 1. **Never invent UI primitives** — only use components available in the customer's UI library or their custom component set
 2. **Never skip behavioral requirements** — every item in the skill file's contract must be implemented, even if the customer's equivalent doesn't natively support it (add the behavior manually)
-3. **Never break existing code** — the generated `pega-components/` folder is additive; never modify the customer's existing components. This prompt does not wire the integration or verify it — those are separate steps, and they are the only ones permitted to edit the customer's files, confined to the seams their skills enumerate
+3. **Never break existing code** — the generated components folder (`{output_path}`) is additive; never modify the customer's existing components. This prompt does not wire the integration or verify it — those are separate steps, and they are the only ones permitted to edit the customer's files, confined to the seams their skills enumerate
 4. **Never hardcode design tokens** — always reference the customer's token system (variables, constants, theme values)
 5. **Respect the customer's code conventions** — the contents of generated files should look like the customer wrote them
 6. **One folder per component** — each component gets its own folder named after its canonical Pega name; paths are Pega's, contents are the customer's

package/templates/react-sdk-reference/.ai-common/skills/connect-pega-server.md

@@ -4,51 +4,104 @@ ai-description: Ensure the Pega server connection (MCP config + sdk-config.json)
 
 # Pega Server Connection Gate
 
-Run this **before** the first Pega data source is executed in a chat session. It ensures the MCP server this session talks to, and `sdk-config.json`, both carry real connection values instead of the placeholder markers the project scaffolding step leaves behind. Scaffolding never asks for these — this gate is where they are actually collected, the first time a workflow needs them.
+Run this **before** the first Pega data source is executed in a chat session. It applies to both full-portal and embedded workflows. It resolves connection values from the project's existing configuration, asks once for everything still missing, and synchronizes the active MCP config and browser-served `sdk-config.json`.
 
-## 1. Locate the MCP config file
+## 1. Locate the active configuration files
 
-Find the file this session's AI tool reads its Pega MCP server list from. Do not assume a fixed name or path, and do not ask the user which file to edit — discover it by what it contains: a server entry whose key starts with `pega-`, holding a `url` that points at an `/api/service/v1/mcp/` endpoint. Search the project for a file matching that shape.
+### 1.1 MCP config
 
-## 2. Check whether it is already configured
+Find the file this session's AI tool reads its Pega MCP server list from. Do not assume a fixed name or ask the user which file to edit. Search the project for a server entry whose key starts with `pega-` and whose `url` contains `/api/service/v1/mcp/`.
 
-Read that file and `sdk-config.json`. Treat the connection as **already configured** only when none of the following markers remain, literally, in either file: `{InfinityURL}`, `{AppAlias}`, `{MCPRuleName}`, `{MCPRuleInsKey}`, `{ClientId}`, `{ClientSecret}`, and `sdk-config.json`'s `serverConfig.infinityRestServerUrl` / `serverConfig.appAlias` / `authConfig.mashupClientId` are non-empty.
+Classify the active MCP entry by its shape:
 
-If already configured, skip the rest of this gate and continue with the workflow that invoked it.
+- **Cursor-style authenticated MCP** — the entry contains `auth.clientId` and `auth.clientSecret`. Both fields are required for this MCP connection.
+- **URL-only MCP** — the entry has no auth fields, as in Copilot and Claude Code. Do not require, search for, warn about, or mention a client secret for this entry.
 
-## 3. Ask only for what is still missing
+### 1.2 Browser-served SDK config
 
-Check each value independently — ask only for the ones still a marker or blank, never re-ask for a value already present:
+Find the `sdk-config.json` the application actually serves to the browser. Do not automatically choose a same-named file at the project root:
 
-- Pega server URL
-- Application alias
-- OAuth client ID
-- MCP rule name
-- MCP rule instance key
-- **Client secret — only if the MCP config's server entry has an `auth` block containing a `clientSecret` field.** Some MCP configurations authenticate this way and some do not; let the file's own structure decide whether to ask, rather than deciding by which AI tool is running. If there is no `auth` block, do not ask for a client secret at all.
+- For an embedded project, identify the framework's served static directory (for example `public/`, `static/`, or another directory established by its build configuration) and use the `sdk-config.json` there.
+- For a full-portal project, use its scaffolded application `sdk-config.json`.
+- If more than one copy exists, determine which one the application serves. Report other copies as potentially stale and do not update them.
 
-Ask these as a single batch of questions, not one at a time.
+### 1.3 Environment files
 
-## 4. Write the values
+Environment files are commonly excluded by `.gitignore`, so do not rely on an ordinary recursive file search or glob to discover them. First enumerate the project-root directory, including dotfiles, then read every root entry named `.env` or beginning with `.env.` directly by its exact path. If directory enumeration is unavailable, search with ignored files explicitly included. A zero-result ignore-aware search is not evidence that no environment files exist.
 
-**MCP config file** — replace each marker with the value collected for it, and rename the `pega-{MCPRuleName}` server key using the real rule name:
+Read project-root environment files such as `.env`, `.env.local`, `.env.development`, `.env.production`, and other `.env.*` variants. Never print a secret value.
 
-- `{InfinityURL}` → server URL
-- `{AppAlias}` → application alias
-- `{MCPRuleName}` → MCP rule name (in both the server key and the URL path)
-- `{MCPRuleInsKey}` → MCP rule instance key
-- `{ClientId}` → client ID, if the entry has an `auth` block
-- `{ClientSecret}` → client secret, if the `auth` block has that field
+## 2. Build the connection inventory
 
-**`sdk-config.json`** — write into the existing structure, do not create new fields:
+Resolve each field independently from every applicable source. A value is unresolved when it is blank or still contains its scaffold marker.
 
-- `serverConfig.infinityRestServerUrl` → server URL
-- `serverConfig.appAlias` → application alias
-- `authConfig.mashupClientId` → client ID
-- `authConfig.portalClientId` → client ID (same value as `mashupClientId`)
+| Field                  | Allowed sources                                                                                                           | Destinations                                                   |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Pega server URL        | `serverConfig.infinityRestServerUrl`, the MCP URL, or a matching environment key                                          | SDK config and MCP URL                                         |
+| Application alias      | `serverConfig.appAlias`, the MCP URL, or a matching environment key                                                       | SDK config and MCP URL                                         |
+| MCP rule name          | The `pega-*` MCP server key or a matching environment key                                                                 | MCP server key only                                            |
+| MCP rule instance key  | The MCP URL segment after `/api/service/v1/mcp/` or a matching environment key                                            | MCP URL                                                        |
+| OAuth client ID        | `authConfig.mashupClientId`, `authConfig.portalClientId`, MCP `auth.clientId` when present, or a matching environment key | Both SDK client-ID fields and MCP `auth.clientId` when present |
+| Pega MCP client secret | A private environment key only, and only when the MCP entry contains `auth.clientSecret`                                  | MCP `auth.clientSecret` only                                   |
 
-Never write the client secret into `sdk-config.json` — it belongs only in the MCP config file's `auth.clientSecret`.
+The five non-secret fields are required for every tool. The client ID is a public OAuth identifier and may be supplied in chat. A client secret is required only by a Cursor-style authenticated MCP entry; it is not required for the browser SDK or a URL-only Copilot/Claude Code MCP entry.
 
-## 5. Tell the user to reconnect
+For non-secret environment values, recognize clear semantic keys ending in `INFINITY_URL`, `SERVER_URL`, `APP_ALIAS`, `MCP_RULE_NAME`, `MCP_RULE_INS_KEY`, `MCP_RULE_INSTANCE_KEY`, or `CLIENT_ID`, including project conventions such as `PEGA_`, `VITE_`, `NEXT_PUBLIC_`, `REACT_APP_`, and `EXPO_PUBLIC_`.
 
-Most AI tools read their MCP config once at startup. After writing these values, tell the user the MCP server configuration changed and they need to reload or reconnect it (tool-dependent — e.g. restarting the MCP connection or reloading the window) before their request can proceed, and ask them to retry once reconnected.
+For a client secret, accept only a private key such as `PEGA_CLIENT_SECRET` or `CLIENT_SECRET`. Reject browser-exposed names beginning with `VITE_`, `NEXT_PUBLIC_`, `REACT_APP_`, or `EXPO_PUBLIC_`. Never infer a value from an unrelated key merely because it is the only candidate.
+
+Record each field's source and status: configured, missing, or conflicting. For a secret, record presence and source only, never its value.
+
+## 3. Resolve conflicts before writing
+
+If allowed sources contain different real values for the same non-secret field, show the field and each source/value pair and ask the user which source is authoritative. Do not silently choose or overwrite.
+
+If private environment files contain different client-secret values for a Cursor-style MCP entry, state that the secret sources disagree and name only the files and keys. Ask which environment key is authoritative without exposing either value.
+
+Equivalent values across sources are not conflicts; consolidate them without asking.
+
+## 4. Ask once for every unresolved value
+
+After reading all sources, make the first user interaction complete. Show a status table for every applicable field, using only **configured**, **missing**, or **conflicting**. For the client secret, show presence only.
+
+In that same response:
+
+1. Ask for every missing or conflict-resolved **non-secret** value as one batch. The user may provide these values directly in chat.
+2. Explain that the user may instead edit any allowed source and say when it is ready. Name the exact destinations:
+   - Environment: matching semantic keys for any non-secret field.
+   - Active `sdk-config.json`: `serverConfig.infinityRestServerUrl`, `serverConfig.appAlias`, `authConfig.mashupClientId`, and `authConfig.portalClientId`.
+   - MCP config: `{InfinityURL}` and `{AppAlias}` in the URL, `{MCPRuleName}` in the server key, `{MCPRuleInsKey}` in the URL, and `auth.clientId` when that field exists.
+3. If and only if the active MCP entry contains `auth.clientSecret` and no valid private environment value exists, explain in this first response that the **Pega MCP client secret** is missing. Tell the user to add `PEGA_CLIENT_SECRET` or another private `CLIENT_SECRET`-style key to a project-root environment file and confirm when ready. Never ask them to paste it into chat, put it in `sdk-config.json`, use a browser-exposed env key, or enter it directly into the MCP JSON.
+
+Do not stop after reporting a missing Cursor secret without also asking for every missing non-secret value. On every reply or retry, re-read all configuration sources and ask again only for fields that remain unresolved.
+
+## 5. Synchronize resolved values
+
+Once all five non-secret fields are resolved — and, for a Cursor-style MCP entry, a private environment-sourced secret is resolved — update the active files while preserving unrelated fields.
+
+**MCP config:**
+
+- Replace `{InfinityURL}` with the server URL.
+- Replace `{AppAlias}` with the application alias.
+- Rename the `pega-{MCPRuleName}` server key with the real MCP rule name. The rule name belongs in the server key, not the endpoint URL.
+- Replace `{MCPRuleInsKey}` with the MCP rule instance key.
+- When `auth.clientId` exists, write the resolved client ID.
+- When `auth.clientSecret` exists, write the private environment-sourced secret without displaying it.
+- Never add an auth block to a URL-only MCP entry.
+
+**Active browser-served `sdk-config.json`:**
+
+- Write the server URL to `serverConfig.infinityRestServerUrl`.
+- Write the application alias to `serverConfig.appAlias`.
+- Write the client ID to both `authConfig.mashupClientId` and `authConfig.portalClientId`.
+- Do not create new fields or change unrelated values.
+
+Never write a client secret into `sdk-config.json`, including `authConfig.portalClientSecret`. This file is served to the browser and is publicly readable. The user's browser-runtime OAuth grant configuration remains their choice; this gate only ensures the required public client ID is present.
+
+After writing, re-read both active files and repeat the inventory check. Continue only when all applicable markers are gone, the five non-secret values are non-empty and consistent, and a Cursor-style `auth.clientSecret` was populated from a private environment value. A URL-only MCP entry is complete without any client secret.
+
+## 6. Continue or reconnect
+
+- If the MCP config changed, tell the user it must be reloaded or reconnected before a Pega data source can run, then stop. Ask them to retry the original request; the invoking workflow must rerun this gate first. If MCP tools were started or attached after the conversation began and are not bound to this session, tell the user to start a new chat session.
+- If only `sdk-config.json` changed and the MCP connection is already available to the conversation, continue the invoking workflow without requiring an unnecessary MCP reconnect.
+- If neither file needed changes, continue immediately.

package/templates/react-sdk-reference/.ai-common/skills/embedded-flow/analyze-customer-repo.md

@@ -28,6 +28,15 @@ When Pega case flows are embedded into a customer's existing application, the ge
 
 ## Steps
 
+### Step 0 — Resolve the output path
+
+Every downstream skill and prompt writes generated components to one location: `{output_path}`. Resolve it once, here, before anything else runs. This is separate from the Design Profile document itself, which always lives at the fixed `docs/design-profile.md` and never moves with `{output_path}`.
+
+1. **Check for an existing profile first.** Look for `docs/design-profile.md` at the project root — this is its one fixed location, independent of `{output_path}`. If it exists, read its **Output Path** field (Section 1) and reuse that value as `{output_path}` — skip the rest of this step entirely. Do not ask the user again.
+2. **Otherwise, ask.** Ask the user where in their own project the generated Pega components should live. Suggest `pega-components/` at the project root as the default/recommended answer, but accept any path they type instead.
+3. **Validate the answer stays inside the project.** Reject an absolute path outside the project, any `..` traversal segment, or anything else that would resolve outside the project root — re-ask when this happens rather than writing outside the repo.
+4. **Record the confirmed path** as `{output_path}`. It is written into the Design Profile in Step 6 below, and every other embedded-flow skill/prompt reads it from there instead of asking again or assuming a fixed name.
+
 ### Step 1 — Identify project fundamentals
 
 Read the project's dependency manifest (the file that lists packages and their versions). From it, determine:
@@ -105,7 +114,7 @@ This is what makes it possible to offer the user real choices in their own vocab
 
 Produce a structured markdown document with the following sections. Use heading levels for organization and bullet lists for values. Do not include source code — describe patterns in prose and reference file paths for the AI to read during generation.
 
-**Section 1: Project Fundamentals** — list the framework name and version, language and configuration, UI library name and version (or "Custom"), styling approach, form handling library or pattern, and module system.
+**Section 1: Project Fundamentals** — start with the **Output Path** resolved in Step 0, then list the framework name and version, language and configuration, UI library name and version (or "Custom"), styling approach, form handling library or pattern, and module system.
 
 **Section 2: Design Tokens** — organize by sub-sections: Colors (primary, secondary, accent, error, warning, success, background, text, border with their semantic names and values), Spacing (scale), Typography (font families, sizes, weights), Borders and Radii (values), Shadows (elevation values), Breakpoints (if defined).
 
@@ -119,7 +128,7 @@ Produce a structured markdown document with the following sections. Use heading
 
 **Section 7: Navigation and Surfaces** — list the routing approach and how navigation is triggered, the overlay primitives the project uses and where they come from, the layout shell that wraps a routed page, and a table of existing task entry points giving each control's visible label, its file, and what it does today. The wiring workflow reads this section to decide where the embedded flow renders.
 
-Save this document to `pega-components/.design-profile.md` in the customer's project.
+Save this document to `docs/design-profile.md` in the customer's project, creating the `docs/` folder at the project root first if it does not already exist. This location is fixed — it does not move with `{output_path}`.
 
 ---
 

package/templates/react-sdk-reference/.ai-common/skills/embedded-flow/wire-integration.md

@@ -6,7 +6,7 @@ Guide the wiring of generated Pega components into a customer's existing applica
 
 ## Purpose
 
-After the `pega-components/` folder has been generated (via the component generation prompt), this skill describes the steps to integrate the Pega SDK into the customer's application — connecting authentication, bootstrapping the runtime, launching case flows on user action, and rendering the flow within the application's layout.
+After the generated components folder (its location is resolved during analysis and recorded in the Design Profile) has been generated (via the component generation prompt), this skill describes the steps to integrate the Pega SDK into the customer's application — connecting authentication, bootstrapping the runtime, launching case flows on user action, and rendering the flow within the application's layout.
 
 **Step 0 is the exception.** It is a gate, not an integration step, and it runs _before_ generation — see its own heading for why.
 
@@ -14,7 +14,7 @@ After the `pega-components/` folder has been generated (via the component genera
 
 ## Prerequisites
 
-- The `pega-components/` folder exists with generated components and a registry file named `component-map` (the extension follows the customer's framework) — required from **Step 1 onward**. Step 0 runs before generation and needs only the customer's codebase and the Design Profile
+- The generated components folder (its location is resolved during analysis and recorded in the Design Profile) exists with generated components and a registry file named `component-map` (the extension follows the customer's framework) — required from **Step 1 onward**. Step 0 runs before generation and needs only the customer's codebase and the Design Profile
 - The customer has a Pega Infinity environment with:
   - An OAuth 2.0 client configured for the application
   - A case type to embed (e.g., a service request, onboarding flow)
@@ -155,7 +155,7 @@ Add the following Pega packages to the project's dependency manifest:
 | The Pega SDK types package                                       | Shared type definitions and interfaces                          |
 | The Pega ConstellationJS core package                            | Runtime engine that provides the PCore global                   |
 
-These are the only external additions. The generated `pega-components/` use the customer's existing UI library — no additional design system packages are needed.
+These are the only external additions. The generated components use the customer's existing UI library — no additional design system packages are needed.
 
 If SDK packages were provided as `.tgz` files (interim distribution), they should already be in the project root with `file:` references in the dependency manifest. Run the project's package install command to link them.
 
@@ -295,7 +295,7 @@ The module-scoped singleton avoids this entirely because it is immune to compone
 
 1. **Authenticate** — use the SDK auth client to perform login (OAuth redirect or silent renewal)
 2. **Bootstrap in embedded/mashup mode** — initialize the SDK runtime in mashup mode (not full portal), capturing the render context returned by bootstrap
-3. **Create the component registry** — instantiate the SDK's component registry and register all components exported by the generated `pega-components/component-map` registry file
+3. **Create the component registry** — instantiate the SDK's component registry and register all components exported by the generated components folder's `component-map` registry file
 4. **Register the component creator** — tell the SDK runtime to use the registered components for rendering
 
 This module should expose:
@@ -433,7 +433,7 @@ Do not report the integration as complete on static checks alone.
 │  │  │                                                  │  │   │
 │  │  │  SDK Bridge Component                            │  │   │
 │  │  │    ↓ resolves from registry                      │  │   │
-│  │  │  pega-components/ (generated, customer-styled)   │  │   │
+│  │  │  generated components folder (generated, customer-styled) │  │   │
 │  │  │    ↓ wired to                                    │  │   │
 │  │  │  PConnect (Pega runtime state + actions)         │  │   │
 │  │  └─────────────────────────────────────────────────┘  │   │
@@ -470,7 +470,7 @@ Common integration failures and their resolutions. These are ordered by how they
 
 ## Notes
 
-- The generated `pega-components/` folder has zero dependencies beyond the customer's existing UI library and the Pega SDK packages. No additional design system installation is needed.
+- The generated components folder (its location is resolved during analysis and recorded in the Design Profile) has zero dependencies beyond the customer's existing UI library and the Pega SDK packages. No additional design system installation is needed.
 - The bootstrap module should handle token refresh/silent renewal automatically via the SDK auth client.
 - If the customer's app already has authentication, coordinate with their auth flow — the SDK auth client can share tokens if the same OAuth provider is used.
 - The Pega rendering container can be a modal, a sidebar, an inline section, or a full page. Which one is not a matter of taste — it is resolved in Step 0.2 from what the user asked for or from what their application already does.