@pega/sdk 0.0.9 → 0.0.12

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,15 @@ 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. There are two ways to fill them in:
+
+- **AI coding assistant (recommended)** — the first time you ask it to do something
+  that needs a live Pega server (e.g. generating components from your app's real
+  portals/case types), it asks you for the server URL, application alias, OAuth
+  client ID, and MCP rule details in chat, then writes them into both files itself.
+- **Manual** — edit `sdk-config.json` in the project root yourself:
 
 ```jsonc
 {
@@ -153,6 +163,11 @@ environment details:
 - `appAlias` — the application alias to load
 - `mashupClientId` / `portalClientId` — OAuth 2.0 client IDs registered in Pega
 
+You'll also need to fill in the generated MCP config file (`.vscode/mcp.json` for
+Copilot, `.cursor/mcp.json` for Cursor, or `.mcp.json` for Claude Code) — replace
+its `{InfinityURL}`/`{AppAlias}`/`{MCPRuleName}`/`{MCPRuleInsKey}` markers the same
+way if editing manually.
+
 ## 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.9",
+  "version": "0.0.12",
   "description": "Scaffold a Pega SDK application project",
   "type": "module",
   "bin": {

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

@@ -53,6 +53,10 @@ Determine which workflow governs the request, then execute it by reading the ref
 
 ⛔ **This step MUST complete before any component generation begins.** Do NOT use hardcoded component lists. Both the case type and the component list MUST come from the Pega server.
 
+### 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.
+
 ### Step 0.1 — Check for a case type in the prompt
 
 Scan the user's message for a **Pega case type class name** (hyphen-separated segments like `DIXL-MediaCo-Work-NewService`). Note whether one was found — it will be needed in Step 0.2.
@@ -61,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.
@@ -77,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.
 
@@ -153,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 customer must fill in their server URL, app alias, OAuth client ID, and case type.
+`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.
 
 ---
 

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 AI assistant gathers the server URL, app alias, OAuth client ID, and MCP rule details from the user in chat the first time a workflow needs a live Pega server (e.g. resolving portals/components in Section 15), and fills them into both files automatically — see `{{SKILL_DIR}}/connect-pega-server.md`.
+
 ---
 
 ## 2. What Is Replaceable vs. Infrastructure

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

@@ -4,7 +4,7 @@
       "url": "{InfinityURL}/app/{AppAlias}/api/service/v1/mcp/{MCPRuleInsKey}",
       "auth": {
         "clientId": "{ClientId}",
-        "clientSecret": "<YOUR_CLIENT_SECRET>"
+        "clientSecret": "{ClientSecret}"
       }
     }
   }

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

@@ -55,21 +55,26 @@ Once design system, base folder, and type scope are resolved, continue to Step 0
 
 ⛔ **This step MUST complete before anything is read, installed, or written.** A portal renders a specific set of components, and generating the full catalogue produces components the portal will never mount. Do NOT use a hardcoded component list, and do NOT infer one from the project's existing folders.
 
+### 0.5.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.
+
 ### 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:
 
 1. If the user's message did NOT name a portal, present the returned portals as a numbered pick-list and ask which one to generate for.
 2. If the user's message DID name one, confirm it appears in the response. If it does not, show what the server returned and ask the user to choose from that list. Never proceed on an unverified portal name.
 3. Record the confirmed entry's **`pyPortalLayout`** value. This — not the display label shown to the user — is what Steps 0.5.3 and 0.5.4 pass to the server as `PortalName`; carry it forward exactly as the data page returned it.
+4. Write the confirmed `pyPortalLayout` value into `sdk-config.json` field `serverConfig.appPortal`.
 
 ### 0.5.2 — Ask what to convert
 
@@ -83,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.
@@ -110,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.
 
@@ -539,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/skills/connect-pega-server.md

@@ -0,0 +1,54 @@
+---
+ai-description: Ensure the Pega server connection (MCP config + sdk-config.json) is configured before any workflow executes a live Pega data source. Not a standalone flow — invoked as a prerequisite step by other skills/prompts.
+---
+
+# 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.
+
+## 1. Locate the MCP config file
+
+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.
+
+## 2. Check whether it is already configured
+
+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.
+
+If already configured, skip the rest of this gate and continue with the workflow that invoked it.
+
+## 3. Ask only for what is still missing
+
+Check each value independently — ask only for the ones still a marker or blank, never re-ask for a value already present:
+
+- 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.
+
+Ask these as a single batch of questions, not one at a time.
+
+## 4. Write the values
+
+**MCP config file** — replace each marker with the value collected for it, and rename the `pega-{MCPRuleName}` server key using the real rule name:
+
+- `{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
+
+**`sdk-config.json`** — write into the existing structure, do not create new fields:
+
+- `serverConfig.infinityRestServerUrl` → server URL
+- `serverConfig.appAlias` → application alias
+- `authConfig.mashupClientId` → client ID
+- `authConfig.portalClientId` → client ID (same value as `mashupClientId`)
+
+Never write the client secret into `sdk-config.json` — it belongs only in the MCP config file's `auth.clientSecret`.
+
+## 5. Tell the user to reconnect
+
+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.