@pega/sdk 0.0.4 → 0.0.6

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

@@ -0,0 +1,130 @@
+# Skill: Analyze Customer Repository
+
+Scan a customer's application codebase and produce a structured **Design Profile** document that captures their design system, coding conventions, and component patterns. This profile is consumed by the component generation workflow to produce Pega components that blend seamlessly with the customer's existing application.
+
+---
+
+## Purpose
+
+When Pega case flows are embedded into a customer's existing application, the generated Pega components must visually and structurally match the host application. This skill extracts the information needed to achieve that match.
+
+---
+
+## What to Extract
+
+| Aspect                           | Discovery approach                                                                       | Output                                                                                                                                                               |
+| -------------------------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Framework & language**         | Read project configuration and dependency manifest                                       | Framework name + version, primary language, module system                                                                                                            |
+| **UI component library**         | Identify UI/component packages in dependencies                                           | Library name + version (or "custom" if no third-party library)                                                                                                       |
+| **Theme & design tokens**        | Search for theme configuration files, token/variable definitions, style constants        | Token inventory: colors (primary, secondary, error, background, text), spacing scale, typography (font families, sizes, weights), border radii, shadows, breakpoints |
+| **Component structure patterns** | Read 3–5 representative form-like components (text inputs, selects, buttons, checkboxes) | How they define their input interface, internal state, event handling, and output/rendering                                                                          |
+| **Styling approach**             | Detect the styling mechanism used across components                                      | Identifier (utility classes, CSS modules, CSS-in-JS, scoped styles, inline, etc.) + import/usage pattern                                                             |
+| **File & folder conventions**    | Analyze the project's component directory structure                                      | Naming convention (casing, separators), folder-per-component vs flat, barrel/re-export pattern, test co-location                                                     |
+| **Form & state management**      | Identify form-handling libraries or patterns in dependencies and source                  | Library or pattern name + how values, validation, and submission are handled                                                                                         |
+| **Import & module conventions**  | Analyze import statements across multiple files                                          | Path aliasing, barrel imports, relative vs absolute, grouping order                                                                                                  |
+| **Validation & error display**   | Observe how existing components show validation feedback                                 | Pattern: inline message, tooltip, border color change, icon, combination                                                                                             |
+
+---
+
+## Steps
+
+### Step 1 — Identify project fundamentals
+
+Read the project's dependency manifest (the file that lists packages and their versions). From it, determine:
+
+- The application framework and its version
+- The primary language and its configuration
+- The UI component library (if any) and version
+- Any form-handling, state management, or validation libraries
+- The styling library (if separate from the UI library)
+
+### Step 2 — Locate theme and design token configuration
+
+Search the project for theme/token definitions. Look for:
+
+- Files with "theme", "tokens", "variables", "palette", "colors", or "design" in their name or path
+- Style variable definition files (custom properties, constants, exported objects)
+- Configuration files for utility-class frameworks (if applicable)
+
+Read the discovered files and extract:
+
+- **Color palette** — primary, secondary, accent, error/danger, warning, success, neutral/background, text colors
+- **Spacing scale** — the progression of spacing values used
+- **Typography** — font families, size scale, weight scale, line heights
+- **Border radii** — small, medium, large, full/rounded values
+- **Shadows** — elevation levels used
+- **Breakpoints** — responsive design boundaries (if defined)
+
+### Step 3 — Analyze representative components
+
+Find 3–5 components that handle user input (text fields, selects/dropdowns, checkboxes, date pickers, buttons). Prioritize components that:
+
+- Accept user input and emit value changes
+- Show validation feedback
+- Support disabled/read-only states
+
+For each component, note:
+
+1. **Input interface** — how the component defines what it accepts (typed props, attributes, inputs, parameters)
+2. **Internal state** — how it manages transient state (controlled vs uncontrolled, local vs lifted)
+3. **Event handling** — how it reports value changes and blur/commit events to the parent
+4. **Validation display** — how it shows error messages, styling changes, or icons on invalid state
+5. **Styling mechanism** — how it applies visual styles (class names, style objects, utility classes, scoped selectors)
+6. **Accessibility** — labels, ARIA attributes, focus management
+
+### Step 4 — Determine file and folder conventions
+
+List the project's component directory and observe:
+
+- **Folder structure** — flat list, folder-per-component, grouped by type/feature, or nested
+- **Naming convention** — PascalCase, camelCase, kebab-case, snake_case for files and folders
+- **Module boundaries** — barrel files (index re-exports), direct imports, or path-based resolution
+- **Co-located files** — whether tests, styles, and types live alongside the component or separately
+
+### Step 5 — Analyze import conventions
+
+Read 5–10 import sections across different files and determine:
+
+- **Path resolution** — aliases (e.g., `@/`, `~/`, `#`) vs relative paths
+- **Grouping order** — external packages first, then internal modules, then relative imports (or other order)
+- **Named vs default imports** — which pattern dominates
+- **Style imports** — how stylesheets or style modules are imported
+
+### Step 5.1 — Analyze navigation and presentation surfaces
+
+The embedded flow has to appear somewhere, and that surface should be one the application already uses. Capture how this application presents a self-contained task:
+
+- **Routing approach** — how routes are declared and navigated (file-based, configuration-based, or a router API), and how a route change is triggered from a control
+- **Overlay primitives** — which of dialog, modal, drawer, sheet or popover the project actually uses, where those primitives come from, and how one is opened and dismissed
+- **Existing task entry points** — find 2–3 places where a control starts a multi-step or form-based task, and record for each: the control's visible label, the file it lives in, and what it does — opens an overlay, navigates to a route, or reveals a region in place
+- **Layout shell** — what wraps a routed page (navigation, header, sidebar), so a flow mounted at a route keeps the surroundings the customer expects
+
+This is what makes it possible to offer the user real choices in their own vocabulary instead of a generic list of surfaces, and to infer the right surface when a launch control already has behaviour. Record what exists; do not recommend a surface here.
+
+### Step 6 — Synthesize into Design Profile
+
+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 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).
+
+**Section 3: Component Patterns** — describe each convention as a sub-section: Input Interface Convention (how components define what they accept), State Management Convention (how local state is handled), Event Handling Convention (how value changes are reported — immediate, on blur, debounced), Validation Display Convention (where errors appear, how error styling is applied), Styling Convention (how styles are applied to elements, how conditional styles work).
+
+**Section 4: File Conventions** — list the folder structure type, naming convention (casing), re-export/barrel pattern, test file location, and style file location.
+
+**Section 5: Import Conventions** — list path resolution approach (aliases or relative), grouping order, default vs named import preference, and style import pattern.
+
+**Section 6: Representative Component Examples** — list the 3–5 components analyzed with their file paths and why each was selected (e.g., "text input with validation", "select with async options"). These serve as reference points the generation workflow can re-read for detailed implementation guidance.
+
+**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.
+
+---
+
+## Notes
+
+- If the project uses no third-party UI library (fully custom components), the "UI Library" field should be "Custom" and the representative component analysis becomes especially important — the generated Pega components will directly replicate the customer's custom primitives.
+- If multiple styling approaches are mixed (e.g., utility classes for layout + component library for inputs), document both and specify which is used where.
+- Do not include actual source code in the Design Profile. Describe patterns in prose. Reference file paths for the AI to read during generation.

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

@@ -0,0 +1,311 @@
+# Skill: Authenticate to Pega
+
+Establish an authenticated OAuth 2.0 session against the customer's Pega server, persist the resulting token locally, and use it to make DX API calls.
+
+> **This skill is not part of the embedded flow.** The embedded flow resolves case types, their starting fields, and their components through the Pega MCP server, and the wired application authenticates itself in the browser at runtime — so no design-time token is needed and no workflow invokes this skill. Do not run it as a prerequisite to embedding, and do not let it write configuration that the embedded flow depends on. It remains available for making DX API calls directly.
+
+---
+
+## Purpose
+
+The embedded flow needs to know which case type to embed, which components that case requires, and how the customer's Pega environment is configured. All of that lives on the Pega server behind an OAuth-protected DX API.
+
+This skill collects connection details, writes them to `.pega-auth.json`, and invokes `npx pega-auth` — the headless CLI shipped inside the `@pega/auth` package — to exchange them for an access token, enrich the token with Constellation bootstrap data, and store it for reuse.
+
+Once complete, the agent can call:
+
+- `/api/application/v2/casetypes` — to list case types and present a pick-list
+- `/api/application/v2/data_views/{D_page}` — to read any data page
+- `D_pxBootstrapConfig` — to read Constellation runtime configuration
+
+---
+
+## Prerequisites
+
+- A reachable Pega Infinity or Launchpad server
+- An **OAuth 2.0 Client Registration** record on that server, configured for the grant type being used
+- For the authorization-code grant: a redirect URI registered on that client record, and a browser available on the machine running the flow
+- For the client-credentials grant: the client registration must be enabled for client credentials and mapped to an operator with DX API access
+
+---
+
+## Storage Contract
+
+Two files at the project root. **Both must be gitignored.**
+
+| File               | Contents                                                            | Committed? |
+| ------------------ | ------------------------------------------------------------------- | ---------- |
+| `.pega-auth.json`  | Collected connection details, including `clientSecret` / `password` | ❌ Never   |
+| `.pega-token.json` | The raw token response, plus `C11NB2S` and `appStaticContentServer` | ❌ Never   |
+| `sdk-config.json`  | Non-secret runtime values only                                      | ✅ Yes     |
+
+⚠️ **`sdk-config.json` is served publicly at the application's web root.** Anything written into it is retrievable by any visitor. Client secrets and passwords must never be written there.
+
+`.pega-auth.json` shape:
+
+```json
+{
+  "serverType": "infinity",
+  "server": "https://example.pega.com/prweb",
+  "grantType": "clientCreds",
+  "authService": "pega",
+  "redirectUri": "https://localhost:4010/",
+  "clientId": "...",
+  "clientSecret": "...",
+  "user": "",
+  "password": "",
+  "isolationId": "",
+  "appAlias": "MediaCo"
+}
+```
+
+`.pega-token.json` shape (the token endpoint response, plus two enrichment fields):
+
+```json
+{
+  "token_type": "Bearer",
+  "access_token": "...",
+  "refresh_token": "...",
+  "expires_in": 3600,
+  "obtained_at": 1753833600000,
+  "C11NB2S": "...",
+  "appStaticContentServer": "https://..."
+}
+```
+
+---
+
+## Steps
+
+### Step 1 — Detect an existing session
+
+Read `.pega-token.json` if it exists.
+
+- If it contains an `access_token` and `obtained_at + expires_in * 1000` is still in the future, tell the user which server the session belongs to and ask whether to reuse it. On reuse, **skip to Step 6**.
+- If the token is expired and a `refresh_token` is present, attempt a refresh (Step 4c) before falling back to a full re-authentication.
+- If no token file exists, continue to Step 2.
+
+Never print the token value itself — refer to it only by its presence and expiry.
+
+### Step 2 — Collect connection details
+
+Ask for each value below **in this order**. Only ask a question when its condition is met.
+
+| #   | Prompt                                                                   | Key            | Default                        | Ask when                                                                                              |
+| --- | ------------------------------------------------------------------------ | -------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| 1   | Enter Pega server type                                                   | `serverType`   | `infinity`                     | Always                                                                                                |
+| 2   | Enter Pega server url                                                    | `server`       | `https://localhost:1080/prweb` | Always                                                                                                |
+| 3   | Enter OAuth 2.0 grant type                                               | `grantType`    | `authCode`                     | Always                                                                                                |
+| 4   | Enter authentication service alias                                       | `authService`  | `pega`                         | `serverType` is `infinity` **and** `grantType` is `authCode`                                          |
+| 5   | Enter valid redirect URI within the OAuth 2.0 client registration record | `redirectUri`  | `https://localhost:4010/`      | `serverType` is `infinity` **and** `grantType` is `authCode`                                          |
+| 6   | Enter user id                                                            | `user`         | —                              | `serverType` is `infinity` **and** `grantType` is `passwordCreds`                                     |
+| 7   | Enter password                                                           | `password`     | —                              | `user` was answered **and** `serverType` is `infinity` **and** `grantType` is `passwordCreds`         |
+| 8   | Enter clientId                                                           | `clientId`     | —                              | Always                                                                                                |
+| 9   | Enter clientSecret                                                       | `clientSecret` | —                              | (`serverType` is `infinity` **and** `grantType` is not `authCode`) **or** `serverType` is `launchpad` |
+
+**Allowed values:**
+
+| Key          | Values                                                                                                      |
+| ------------ | ----------------------------------------------------------------------------------------------------------- |
+| `serverType` | `infinity`, `launchpad`                                                                                     |
+| `grantType`  | `authCode` (Authorization code), `passwordCreds` (Password credentials), `clientCreds` (Client credentials) |
+
+`passwordCreds` is **not supported on Launchpad** — omit it from the choices when `serverType` is `launchpad`.
+
+**Launchpad only:** additionally ask for `isolationId` if the customer's Launchpad tenant requires one.
+
+**Pre-filling (do not re-ask what is already known):**
+
+Resolve each value from the first source that has a non-empty entry:
+
+1. `.pega-auth.json`
+2. `sdk-config.json` — `serverConfig.infinityRestServerUrl` → `server`, `serverConfig.appAlias` → `appAlias`, `authConfig.authService` → `authService`, `authConfig.mashupClientId` → `clientId`, `authConfig.mashupUserIdentifier` → `user`
+3. The defaults in the table above
+
+Present the resolved values as a summary and ask the user to **confirm or amend** them, rather than prompting for each one individually. Only fall back to asking question-by-question for values that could not be resolved.
+
+**Secret handling:** never ask the user to paste a `clientSecret` or `password` into chat if it can be avoided. Prefer reading them from an environment variable (`PEGA_CLIENT_SECRET`, `PEGA_PASSWORD`) or from an existing `.pega-auth.json`. If the user must supply one, tell them to place it in `.pega-auth.json` directly and confirm when done.
+
+**Normalization:** ensure `server` and `redirectUri` end with a trailing `/` before building any URL from them, then join path segments without duplicating slashes.
+
+### Step 3 — Persist the collected configuration
+
+Write the confirmed values to `.pega-auth.json`. Confirm the file is gitignored (see Step 7) **before** writing any secret into it.
+
+### Step 4 — Obtain an access token
+
+Run the `@pega/auth` headless CLI from the project root:
+
+```
+npx pega-auth
+```
+
+The CLI reads `.pega-auth.json`, performs the OAuth token exchange, and writes `.pega-token.json`. It handles all grant types, token refresh, enrichment, and `sdk-config.json` synchronization in a single invocation.
+
+**What the CLI does internally (for reference — the agent does not need to replicate this):**
+
+1. Checks `.pega-token.json` for an unexpired token — reuses if fresh
+2. Attempts `refresh_token` exchange if the token is expired but a refresh token exists
+3. Falls back to full authentication using the `grantType` in `.pega-auth.json`
+4. For `authCode`: opens the system browser for OAuth consent (requires a human to complete)
+5. For `clientCreds` / `passwordCreds`: completes headlessly with no interaction
+6. On success: writes token to `.pega-token.json`, fetches `D_pxBootstrapConfig` (Infinity only), and mirrors non-secret values into `sdk-config.json`
+
+**Exit codes:**
+
+| Code | Meaning                                                        |
+| ---- | -------------------------------------------------------------- |
+| `0`  | Success — token is fresh and `.pega-token.json` is ready       |
+| `1`  | Invalid config or missing `.pega-auth.json`                    |
+| `2`  | Authentication failed (bad credentials, disabled client, etc.) |
+
+**CLI options (all optional):**
+
+| Flag                  | Default            | Purpose                   |
+| --------------------- | ------------------ | ------------------------- |
+| `--config <path>`     | `.pega-auth.json`  | Path to auth config file  |
+| `--token <path>`      | `.pega-token.json` | Path to token output file |
+| `--sdk-config <path>` | `sdk-config.json`  | Path to SDK config file   |
+
+**Environment variable overrides:**
+
+Secrets can be supplied via environment variables instead of writing them into `.pega-auth.json`:
+
+| Variable             | Overrides      |
+| -------------------- | -------------- |
+| `PEGA_CLIENT_SECRET` | `clientSecret` |
+| `PEGA_PASSWORD`      | `password`     |
+
+**Interpreting output:**
+
+All CLI output goes to stderr. On exit code `0`, read `.pega-token.json` to confirm `access_token` is present and proceed to Step 5.
+
+On a non-zero exit code, read stderr for the specific error and consult the Troubleshooting section.
+
+**Notes:**
+
+- The CLI reads secrets from `.pega-auth.json` or env vars — they never appear on the command line or in the process list.
+- Local/lab servers with self-signed certificates are handled via `"ignoreInvalidCerts": true` in `.pega-auth.json`.
+- The `authCode` grant opens a browser and a local HTTPS listener on the configured `redirectUri`. A human must complete consent in the browser.
+- Prefer `clientCreds` for agent-driven workflows — it requires no human interaction.
+
+### Step 5 — Verify enrichment
+
+**Infinity only.** Launchpad has no equivalent step — skip it.
+
+The CLI (Step 4) automatically fetches `D_pxBootstrapConfig` and writes the enrichment values into `.pega-token.json`. Verify they are present:
+
+| Field in `.pega-token.json` | Source (fetched by the CLI)                         | Purpose                               |
+| --------------------------- | --------------------------------------------------- | ------------------------------------- |
+| `C11NB2S`                   | `pyConfigJSON.tokens.C11NB2S`                       | Constellation browser-to-server token |
+| `appStaticContentServer`    | `pyConfigJSON.serviceConfig.appStaticContentServer` | Static content CDN URL                |
+
+If these fields are missing (the CLI prints a warning when enrichment fails), the token is still valid for DX API calls but the runtime won't have CDN configuration. The most common cause is a `403` on `D_pxBootstrapConfig` — the operator's access group lacks the Constellation runtime privilege.
+
+**Verification criterion:** `.pega-token.json` contains both `access_token` and `C11NB2S`.
+
+### Step 6 — Verify the session and make DX API calls
+
+All DX API v2 calls use the same authorization header:
+
+```
+Authorization: Bearer {access_token}
+```
+
+When an `appAlias` is configured, address the application-scoped base instead of the default one:
+
+| Scope               | Base URL                                     |
+| ------------------- | -------------------------------------------- |
+| Default application | `{server}/api/application/v2`                |
+| Aliased application | `{server}/app/{appAlias}/api/application/v2` |
+
+Because `server` already includes the context root, the aliased base resolves to e.g. `https://example.pega.com/prweb/app/MediaCo/api/application/v2`. Do not add a second context-root segment.
+
+These operations belong to the **Constellation DX APIs** service package. To confirm exact paths, parameters, and response schemas for a given Infinity version, open the API explorer on the target server and select that service package.
+
+**List case types** — this is what allows the case type to be chosen from a list rather than typed:
+
+```
+GET {base}/casetypes
+```
+
+This operation takes **no parameters**. The response has the shape:
+
+| Field                                  | Meaning                                                                                             |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `applicationIsConstellationCompatible` | Whether the application can run Constellation at all                                                |
+| `caseTypes[].ID`                       | The **fully qualified class name** (e.g. `DIXL-MediaCo-Work-NewService`) — this is the value needed |
+| `caseTypes[].name`                     | Display label to show the user                                                                      |
+| `caseTypes[].links`                    | Creation affordance — `href`, `rel`, `type`, and a `request_body` describing the create payload     |
+
+⛔ **Check `applicationIsConstellationCompatible` first.** If it is `false`, stop and tell the user that the target application is not Constellation-compatible and the embedded flow cannot work against it. Do not proceed to analysis, generation, or wiring — the failure would otherwise only surface much later as an unexplained runtime error.
+
+Present `caseTypes` to the user as a numbered pick-list of `name — ID` pairs and have them choose one. The chosen `ID` is the fully qualified class name. The endpoint already returns only the case types the authenticated operator is permitted to create, so no additional filtering is required.
+
+`links.request_body` describes the payload accepted when creating a case of that type — use it to determine which starting field values the mashup API call can supply (see Step 4 of the wire-integration skill).
+
+**Read any data page:**
+
+| Method                            | Usage                                                                  |
+| --------------------------------- | ---------------------------------------------------------------------- |
+| `GET {base}/data_views/{D_page}`  | Parameters passed as query-string values                               |
+| `POST {base}/data_views/{D_page}` | Parameters passed in a `dataViewParameters` object in the request body |
+
+Use `GET` for parameterless or simply-parameterized pages; use `POST` when the page takes structured parameters or when paging/filtering options are needed.
+
+**Verification criterion:** the case types request returns HTTP 200 with a parsable JSON body containing at least one entry. A `401` means the token is invalid or expired; a `403` means the token is valid but the operator's access group lacks the required privilege.
+
+### Step 7 — Mirror non-secret values into `sdk-config.json`
+
+The CLI (Step 4) automatically syncs non-secret values into `sdk-config.json`. After the CLI completes, the following fields are set:
+
+| `sdk-config.json` field              | Source        |
+| ------------------------------------ | ------------- |
+| `serverConfig.infinityRestServerUrl` | `server`      |
+| `serverConfig.appAlias`              | `appAlias`    |
+| `authConfig.authService`             | `authService` |
+| `authConfig.mashupClientId`          | `clientId`    |
+| `authConfig.portalClientId`          | `clientId`    |
+
+The **one field the CLI does not set** is `serverConfig.appMashupCaseType` — that requires the case type chosen in Step 6. After the user picks a case type, write its `ID` into this field.
+
+⚠️ **`portalClientId` must be non-empty.** If it is missing, the SDK's authentication initializer classifies the session as custom-auth and returns without ever resolving its readiness promise — producing a silent, permanent hang with no network activity and no error. See Step 2 of the wire-integration skill. The CLI ensures this is always populated.
+
+The CLI leaves `authConfig.portalClientSecret`, `authConfig.portalGrantType`, and `authConfig.mashupPassword` present but empty. Secrets are never written to this file.
+
+---
+
+## Security Notes
+
+- `.pega-auth.json` and `.pega-token.json` hold live credentials. Confirm both are gitignored before writing to them, and re-confirm with `git status --ignored` afterwards.
+- Never echo an access token, refresh token, client secret, or password back to the user, into a log, or into a commit message. Refer to them by name only.
+- Prefer `clientCreds` over `passwordCreds` — it avoids handling an end-user password entirely.
+- Treat relaxed TLS verification as a local-development affordance only. Never suggest it for a production or shared environment.
+- If a secret is ever pasted into chat or committed by accident, tell the user to rotate the OAuth client registration record — the value must be considered compromised.
+
+---
+
+## Troubleshooting
+
+| Symptom                                                    | Cause                                                                                                        | Resolution                                                                                                                                                          |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `401` with `invalid_client` from the token endpoint        | `clientId` / `clientSecret` do not match an OAuth client registration record, or the record is disabled      | Verify the values against the client registration record in Dev Studio. Confirm the record is enabled.                                                              |
+| `401` with `invalid_grant`                                 | The grant type requested is not enabled on the client registration record, or the user credentials are wrong | Enable the grant on the record, or correct `user` / `password`.                                                                                                     |
+| `unsupported_grant_type` on Launchpad with `passwordCreds` | Launchpad does not support the password grant                                                                | Use `authCode` or `clientCreds`.                                                                                                                                    |
+| TLS handshake fails / self-signed certificate error        | Local or lab server presents an untrusted certificate                                                        | Add `"ignoreInvalidCerts": true` to `.pega-auth.json` and re-run `npx pega-auth`. Only use against local/lab servers.                                               |
+| `404` on the token endpoint                                | `server` is missing the `/prweb` context root, or path segments were joined with a doubled or missing slash  | Normalize `server` to end with `/` and re-derive the endpoint (see Step 2).                                                                                         |
+| Authorization-code flow hangs with no browser activity     | `npx pega-auth` opened a browser but consent was not completed, or the redirect URI is not registered        | Complete the consent in the browser. Confirm the redirect URI on the client registration record matches `redirectUri` exactly, including its trailing slash.        |
+| Redirect returns "redirect_uri mismatch"                   | `redirectUri` differs from the registered value — most often by a missing trailing slash                     | Make both values byte-identical.                                                                                                                                    |
+| `403` on `D_pxBootstrapConfig`                             | The authenticated operator's access group lacks the privilege to read the bootstrap data page                | Authenticate as an operator with an access group that includes the Constellation runtime privileges.                                                                |
+| `pyConfigJSON` is present but `tokens.C11NB2S` is missing  | The response was only parsed once — `pyConfigJSON` is a JSON **string**                                      | Parse `pyConfigJSON` a second time before reading `tokens` (see Step 5).                                                                                            |
+| `/casetypes` returns an empty array                        | The operator has no creatable case types in that application, or `appAlias` targets the wrong application    | Confirm `appAlias` matches the target application and that the operator can create cases in it.                                                                     |
+| `applicationIsConstellationCompatible` is `false`          | The target application is not enabled for Constellation                                                      | Stop. Confirm `appAlias` points at the intended application; if it does, the application must be made Constellation-compatible before an embedded flow is possible. |
+| Calls succeed, then start returning `401`                  | The access token expired                                                                                     | Re-run `npx pega-auth` — it will attempt a refresh automatically, or perform a fresh login.                                                                         |
+
+---
+
+## Notes
+
+- This skill is a prerequisite for case-type resolution. Do not ask the user for a fully qualified case type class before it has completed — the class name should come from `/casetypes`, not from memory.
+- The token obtained here is used by the **agent**, for design-time DX API calls. It is unrelated to the token the browser obtains at runtime, which the SDK's auth client negotiates from `sdk-config.json`.
+- Re-running this skill is safe. It detects an existing valid session and reuses it rather than forcing a fresh authentication.

package/templates/react-sdk-reference/.ai-common/skills/embedded-flow/run-and-verify-integration.md

@@ -0,0 +1,156 @@
+# Skill: Run and Verify the Embedded Integration
+
+Prove that a wired case flow actually runs in the customer's application — by building it, launching it in a browser, driving it to the case form, and repairing what breaks.
+
+---
+
+## Purpose
+
+Wiring is not verification. A wired integration can compile cleanly and still fail at runtime: a missing registry key, an asset that does not resolve from the launching route, a rendering-boundary violation at the trigger. This skill closes that gap so the customer is not the one who discovers the failure.
+
+Use this after `{{SKILL_DIR}}/embedded-flow/wire-integration.md` has completed. It is the terminal step of the embedded flow.
+
+---
+
+## Rules for this skill
+
+**Resolve, never assume.** Every command comes from the project — its script manifest, its toolchain configuration, its own output. Do not assume a package manager, a framework, a build tool, a port, or a script name. If a needed capability has no script entry, derive the invocation from the tool the project already depends on rather than adding a script.
+
+**Assert behaviour, not implementation.** The stages below describe _what must be true_. Write the checks in whatever form suits the project. Do not treat any wording here as a template to transcribe.
+
+**Never handle credentials.** A human authenticates in a visible browser window. Credentials are never requested, captured, logged, echoed, or written to any file by the agent, in any stage, under any failure condition.
+
+---
+
+## Prerequisites
+
+- The integration is wired and the case-launch trigger is reachable from a route in the running application
+- `sdk-config.json` holds real values for the customer's Pega environment
+- A human is available to authenticate when the flow reaches the Pega login form
+
+---
+
+## Stage 1 — Static gates
+
+No browser, no credentials. Run these first; they are the cheapest and catch the largest class of failures.
+
+1. **Production build.** Resolve and run the project's production build. This matters more than a development build: development servers frequently tolerate rendering-boundary violations that the production build rejects, and a server-rendered route that fails only in production is invisible until deploy.
+2. **Type check.** Run the project's type-check entry point. If it has none, invoke the type checker the project already depends on in a no-emit mode using the project's own compiler configuration. Do not add a script entry for this.
+3. **Lint.** Run the project's lint entry point over the generated component folder and every seam file wiring touched.
+4. **Configuration coherence.** Read the served SDK configuration file and assert that the case type is set and that `portalClientId` is present and non-empty. An empty `portalClientId` makes the SDK classify the session as custom-auth and return without ever resolving its readiness promise — a permanent hang with no network activity, no error, and nothing in the console. It costs nothing to catch here and is close to undiagnosable three stages later.
+
+All of these must pass before continuing. A failure here is almost always agent-owned code or configuration — fix it and re-run this stage.
+
+---
+
+## Stage 2 — Pre-authentication browser checks
+
+### Choosing a browser driver
+
+Prefer a browser automation library already present in the customer's dependency manifest. Only when none exists, add one as a development dependency — this is a permitted seam. Ask before adding it if the project's dependency policy is unclear.
+
+### Starting the application
+
+Start the project's development server and **discover its address from the server's own startup output**. Do not assume a port; a port that is already occupied silently shifts, and a hardcoded assumption then verifies nothing.
+
+If the Pega server named in `sdk-config.json` is unreachable from this environment, stop here. Report that verification is limited to Stage 1, state which host could not be reached, and do not present the run as a failure of the integration.
+
+### Checks
+
+Load the route hosting the case-launch trigger, then assert:
+
+1. The route renders — no server-render failure, no error overlay
+2. The browser console and page-error channels are clean; collect anything that appears
+3. The Pega runtime global is present on the window object before application code needs it
+4. The SDK configuration file and the core runtime script both resolve successfully **from the depth of this specific route**. A reference that works from the application root can still fail from a nested route, and this is the failure it exists to catch
+5. Activating the trigger mounts the Pega container element
+
+Stage 2 is the last point at which failures are cheap to diagnose. Do not skip ahead when a check here fails.
+
+---
+
+## Stage 3 — Authentication handoff
+
+The SDK performs a full-page redirect to the Pega login form. This is expected and is not automated.
+
+1. Run the browser in a mode the human can see and interact with
+2. On navigation to the Pega origin, print a clear, unmissable instruction: sign in in the open browser window; verification resumes on its own afterwards
+3. Wait for navigation back to the application's origin, with a timeout generous enough for a person to read a prompt, find credentials, and complete any second factor
+4. Persist the browser session state afterwards so later runs may skip this stage. Write it to a dedicated directory that holds nothing else — `.pega-verify/` at the project root — so a single ignore rule covers it
+
+Session-state reuse is **best-effort only**. Pega may hold tokens in storage that session snapshots do not capture, in which case this stage simply recurs — that is not a failure.
+
+⚠️ **The saved file contains live session tokens.** Before writing it, add an ignore rule for that directory to the project's version-control ignore file, and confirm the rule is in place. Never commit the file, and never print its contents. Adding the ignore rule is a permitted seam.
+
+---
+
+## Stage 4 — Post-authentication assertions
+
+With the case form rendered:
+
+1. **Case creation succeeded.** The create call returned a case, and no request failed during launch. A rejected create leaves a mounted-but-empty container, which reads as a rendering fault — check this first so it is not misdiagnosed as one. A payload rejected as a unit, with no indication of which value was at fault, points at the seeded starting fields
+2. **The bridge is rendering.** The container has rendered descendants — not an empty container, and not a spinner that never resolves
+3. **The assignment is rendering, not the case view.** The embedded flow launches an assignment. Case-level chrome means the wrong page was launched — assert there is no case stage indicator, no case-history or details tab strip, and no case summary panel. Step navigation _within_ the assignment is expected and is not case chrome
+4. **No fallback markers.** The fallback component renders the name of any component the runtime requested but could not resolve. Its presence anywhere in the rendered output is a registry gap, and the rendered text names exactly which component is missing. Assert there are none. Check assertion 3 first: components that only exist in the case view will surface here as fallback markers when the wrong page was launched, and adding registry entries for them treats the symptom
+5. **A field round-trips.** At least one generated field accepts input and retains its value after the commit event fires. This is what separates a component that renders from a component that is wired
+6. **The flow is where it was launched from.** After the redirect completes, assert the case form is visible on the surface the user triggered it from — the overlay re-opened, or the location restored. Landing on the application's root with no flow visible is the failure this catches, and it is a wiring defect, not a Pega one
+7. **The flow can be launched again.** Dismiss the flow, launch it a second time, and assert the form renders again with empty fields — then dismiss and launch a third time, to prove the second launch was not a one-off recovery. Assert that runtime bootstrap is **not** repeated: only the first launch may issue the bootstrap request, while every launch issues its own case-creation request. A second launch that hangs on a loading state with no request at all means the runtime was discarded with the target and cannot be re-established; a second launch that reveals an empty target, or one still showing the previous case's values, means case creation is bound to set-up rather than to the launch. **Do not stop at the first successful launch** — set-up and first launch coincide, so a single pass cannot see either failure
+8. **Console clean.** No errors during form render or interaction
+9. **Evidence on failure.** Capture a screenshot and the collected console output for any failed assertion
+
+⚠️ **At least one full pass must start from a session with no prior authentication state.** Assertions 2 and 6 only exercise the redirect path on a first authentication; once a session exists the application is never torn down and both pass regardless of whether the launch context was ever persisted. A run that reuses saved session state is valid for everything else, but it cannot be the only run.
+
+---
+
+## Stage 5 — Triage and repair
+
+### What may be fixed
+
+Only code the agent generated, or a declared integration seam.
+
+| Symptom                                                    | Cause                                                       | Fix                                                                   |
+| ---------------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------- |
+| Case view renders instead of the assignment                | The launch call omits the embedded page name                | Correct the arguments to the case-creation call at the trigger seam   |
+| Fallback component appears in the rendered output          | The named component is absent from the registry             | Add the registry entry, generating the component if it does not exist |
+| Type or lint failure in a generated component              | Generated code does not satisfy the project's toolchain     | Correct the generated file                                            |
+| Configuration file or core runtime script fails to resolve | The reference is wrong for the launching route's depth      | Correct the reference at the entry-point seam                         |
+| Pega runtime global undefined                              | Core runtime script missing, mis-ordered, or wrongly loaded | Correct the load order or strategy at the entry-point seam            |
+| Container never mounts on trigger activation               | Trigger not connected, or the host element is absent        | Connect the trigger or add the host element                           |
+| Rendering-boundary error at the trigger                    | The trigger seam crosses a server/client boundary illegally | Restructure the trigger seam, and only the trigger seam               |
+| Field value lost after the commit event                    | The actions-API call is missing or mis-sequenced            | Correct the wiring inside the generated field                         |
+
+### What must only be reported
+
+**Never fix these. Stop and hand back.**
+
+- Anything requiring credentials or a reachable environment — server URL, application alias, client identifier, an empty portal client identifier, a case type that does not exist, authorization refused. These belong to the customer
+- **Any defect in customer code outside the declared seams.** A failing assertion is not permission to edit the customer's application until it passes. Report the file, the symptom, and the likely cause, and stop
+- Anything visual. This skill verifies that the flow renders and functions, never that it looks correct
+
+### The loop
+
+Fix, re-run the stage that failed, continue. Cap the number of repair cycles. On exhausting the cap, or on reaching any report-only class, hand back with the captured evidence and a specific diagnosis rather than continuing to try variations.
+
+---
+
+## Verification summary
+
+Always finish by reporting, whatever the outcome:
+
+- Which stages ran and which passed
+- Every fix applied, with the file and the reason
+- Everything that needs the customer, stated as a concrete action
+- The furthest stage reached, so "done" is never ambiguous between _generated_ and _verified_
+
+---
+
+## Common failures specific to embedded flows
+
+| Symptom                                                           | Cause                                                                                                                                    |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Route renders in development but fails the production build       | A server-rendered component passes a non-serializable value into a client boundary at the trigger seam                                   |
+| Configuration or runtime script returns not-found                 | The reference is relative and the launching route sits deeper than the application root                                                  |
+| Initialization never completes, with no error                     | The portal client identifier is empty, so the session is classified as custom authentication and the initializer's promise never settles |
+| Case stage indicator, case-history tabs, or a case summary appear | The case-creation call omits the embedded page name, so the runtime returns the whole case view instead of the assignment                |
+| A component renders as its own name in plain text                 | The fallback component is standing in for a missing registry key                                                                         |
+| Case form renders but values reset                                | The generated field holds local state without committing through the actions API                                                         |