@pega/sdk 0.0.13 → 0.0.15

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

@@ -8,7 +8,7 @@ Prove that a wired case flow actually runs in the customer's application — by
 
 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.
+Use this after `{{SKILL_DIR}}/embedded-flow/wire-integration{{SKILL_EXT}}` has completed. It is the terminal step of the embedded flow.
 
 ---
 
@@ -20,13 +20,20 @@ Use this after `{{SKILL_DIR}}/embedded-flow/wire-integration.md` has completed.
 
 **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.
 
+**Tell the user where you are, in plain words.** Announce each stage as it starts, counting only the stages that run — "Trying it out — part 2 of 4: Opening your app". Use these names: Stage 1 "Checking the code", Stage 2 "Opening your app", Stage 3 "Signing in", Stage 4 "Testing the form", Stage 5 "Fixing what failed".
+
+**You run every stage yourself, in this conversation.** Start right after wiring, without asking first. Open the browser, drive the application, check the results, and repair what fails. The human's only part is signing in, in the window you open. Never hand the sign-in or any later stage back to the user and end your turn, and never ask them to open the application in their own browser to try it.
+
+**Never lighten a stage.** Do not replace a stage with a smaller or cheaper check because the run is long, the component count is large, or a stage needs a human for a moment. Stop early only for the reasons listed in [Stopping early](#stopping-early).
+
 ---
 
 ## 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
+- The user is in the conversation to sign in when the login window you open asks for it
+- The Design Profile exists — Stage 4 assertions 10 and 11 read its example forms, Global Appearance, and Form Layout Convention
 
 ---
 
@@ -36,10 +43,10 @@ No browser, no credentials. Run these first; they are the cheapest and catch the
 
 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.
+3. **Lint.** Run the project's lint entry point over the generated component folder and every seam file wiring touched. Fix every error in those files. If many still remain after one repair pass, list them grouped by rule and ask the user whether to keep fixing or to continue verification with them noted in the summary.
+4. **Configuration coherence.** Read the served SDK configuration file and assert that the case type is set and that both `mashupClientId` and `portalClientId` are present and non-empty. The embedded login popup reads the mashup identifier and a redirect login reads the portal one; an empty identifier for the active mode 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.
+All of these must pass before continuing, apart from lint errors the user chose to note rather than fix. A failure here is almost always agent-owned code or configuration — fix it and re-run this stage.
 
 ---
 
@@ -47,7 +54,14 @@ All of these must pass before continuing. A failure here is almost always agent-
 
 ### 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.
+Use either of these, in this order of preference:
+
+1. A browser automation library already present in the customer's dependency manifest.
+2. Your AI tool's own browser control, if it has one that can show a window the human can sign in to, follow a login popup, and keep watching the page while they do.
+
+Only when neither is available, add a browser automation library as a development dependency — this is a permitted seam. Ask before adding it if the project's dependency policy is unclear. Ask it in plain words — "I need a browser-testing tool to try the form. Can I add one to your project?" — and keep the term "dependency policy" out of the question. If the user declines, stop per [Stopping early](#stopping-early).
+
+**If the login popup does not work in your tool's own browser** — activating the trigger opens no login window there, or the window opens where the human cannot sign in — that is a limit of the browser, not a wiring defect. Change nothing in the application because of it. Switch to a browser automation library (one already in the project, or one you add after asking as above), tell the user in plain words that you switched browsers and why, and re-run Stage 2 in it before continuing to Stage 3.
 
 ### Starting the application
 
@@ -55,15 +69,27 @@ Start the project's development server and **discover its address from the serve
 
 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.
 
+### Checking the Pega server accepts this application's address
+
+Before anyone is asked to sign in, confirm the Pega server allows browser calls from this application. Send a CORS preflight — an `OPTIONS` request that carries no credentials — to the API path the SDK will call: `{infinityRestServerUrl}/app/{appAlias}/api/application/v2/data_views/D_pxBootstrapConfig` when `serverConfig.appAlias` is set, or `{infinityRestServerUrl}/api/application/v2/data_views/D_pxBootstrapConfig` when it is empty. Send it with the application's real origin, taken from the development server's startup output, as the `Origin` header, `GET` as the requested method, and `authorization,content-type` as the requested headers.
+
+The check passes when the response carries `Access-Control-Allow-Origin` equal to that origin. This is an extra check, not a substitute for the browser checks below.
+
+If the response has no such header, or names a different origin, stop before Stage 3 and report it as a server setting — see [What must only be reported](#what-must-only-be-reported). Do not change the application to work around it. If this environment cannot send the preflight at all, run the same check in the browser instead: after sign-in, watch the first Pega API call and treat a CORS error on it the same way.
+
+When the user says the server setting is updated, run this check again and, once it passes, continue with Stage 2. Nothing needs to be regenerated or rewired.
+
 ### Checks
 
-Load the route hosting the case-launch trigger, then assert:
+Load the route hosting the case-launch trigger **in the browser**, then assert the checks below. Fetching the route or the runtime files over plain HTTP is a useful quick pre-check, but it never satisfies this stage: only a real browser exercises rendering, the console, and the login popup.
+
+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
+3. The runtime global is **absent** before authentication. It is loaded only after login, so its absence here is expected; assert that nothing in the page's HTML or entry module references the core bundle
+4. The SDK configuration file resolves successfully **from the depth of this specific route**, and the runtime shell (`/constellation/bootstrap-shell.js`) and library manifest (`/constellation/lib_asset.json`) resolve as a script and as JSON, **not as the application's HTML**. A reference that works from the application root can still fail from a nested route, and a toolchain that falls back to the entry document answers a missing runtime file with HTML that looks like success — these are the failures this check exists to catch
+5. Activating the trigger starts authentication: a login popup opens, and the target surface shows its loading state rather than an error
 
 Stage 2 is the last point at which failures are cheap to diagnose. Do not skip ahead when a check here fails.
 
@@ -71,13 +97,17 @@ Stage 2 is the last point at which failures are cheap to diagnose. Do not skip a
 
 ## Stage 3 — Authentication handoff
 
-The SDK performs a full-page redirect to the Pega login form. This is expected and is not automated.
+The SDK opens a separate login window. 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
+2. When the login window opens on the Pega origin, print a clear, unmissable instruction: sign in in the open login window; verification resumes on its own afterwards. For example: "Please sign in to Pega in the window that just opened. I'll carry on by myself once you're signed in."
+3. Wait for the login window to close and the application page to move past its loading state, with a timeout generous enough for a person to read a prompt, find credentials, and complete any second factor. Keep waiting in this same turn — do not end your turn and ask the user to come back. The application page itself is not navigated away or reloaded in this flow
 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
 
+If the login window never opens, or closes immediately with an error state reporting a blocked popup, the login did not start from the user's launch action, or the callback assets are missing. Both are wiring defects — diagnose per Stage 5.
+
+If the host was deliberately configured for main-window redirect login instead, the whole window navigates to the Pega login form and back. Run the same handoff, and wait for navigation back to the application's origin.
+
 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.
@@ -93,12 +123,18 @@ With the case form rendered:
 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
+6. **The flow is where it was launched from.** After authentication completes, assert the case form is visible on the surface the user triggered it from, and that the page was not reloaded during login. If redirect login is configured, assert instead that the overlay re-opened or the location was 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
+10. **The form looks like the host.** Pick reference elements from the host's own UI — body text, a label, an input, and a primary button on one of the forms recorded in the Design Profile — and compare their computed styles with the same kinds of element inside the Pega form. Also capture a side-by-side screenshot of the host form and the Pega form for the human to judge.
+    - **Must match:** font family and base text colour. Generated components inherit both, so a difference is a defect — repair it per Stage 5 and re-check
+    - **Report only:** font sizes, accent colour, and corner radius. List each difference with both values next to the screenshot; hosts legitimately use several of each, so these are never forced
+11. **The layout holds.** Measure the visible fields inside the Pega form, and repeat the measurement in two more states: with validation errors showing (submit with a required field empty), and with the form's area narrowed below the stacking width recorded in the Design Profile.
+    - **Must hold:** no two visible fields overlap; nothing is wider than the form's area, so no horizontal scrolling appears inside it; fields in the same column share a left edge; when narrowed, multi-column layouts stack into one column. A failure is a defect — repair it per Stage 5 and re-check
+    - **Report only:** gaps between fields or columns that differ from the Form Layout Convention, with the measured and expected values
 
-⚠️ **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.
+⚠️ **At least one full pass must start from a session with no prior authentication state.** Only a first authentication exercises the login popup, the callback assets, and the hold-the-launch-until-ready behaviour; once a session exists, the runtime is already ready at the first launch and all of these pass regardless of whether they were wired correctly. If redirect login is configured, assertions 2 and 6 also exercise the restoration path only on a first authentication. A run that reuses saved session state is valid for everything else, but it cannot be the only run.
 
 ---
 
@@ -108,28 +144,51 @@ With the case form rendered:
 
 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                         |
+| 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 runtime files fail to resolve                      | The configuration reference is wrong for the launching route's depth, or the `/constellation/` runtime files are not served | Correct the reference or the static-serving rule at the entry-point seam                                                |
+| Pega runtime global undefined after login                                | The runtime files are not served, or login never completed                                                                  | Serve the runtime files per the wiring skill; confirm login finished                                                    |
+| Login window blocked, or closes with an error state                      | Login did not start from the launch action, or the callback assets are missing                                              | Start the runtime from the trigger itself, or place the callback assets 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                                                                           |
+| Pega form uses a different font family or base text colour from the host | A generated component sets its own font or colour, or the Pega container sits outside the host's theme scope                | Remove the override from the generated component, or bring the container into the host's scope at the host-element seam |
+| Fields overlap, overflow the form, or are misaligned                     | A generated field adds its own margins, fixed sizes, or positioning, or a layout template aligns or stacks incorrectly      | Correct the generated field or layout template per the Form Layout rules                                                |
 
 ### 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
+- **A Pega CORS policy that does not allow this application's address.** The browser shows a CORS error on a Pega API call, or the preflight check in Stage 2 fails, and the application stays on its loading state. Never change application code for it. Report the blocked URL and the application's origin, and tell the user how their Pega administrator fixes it:
+  - In Pega, open **Endpoint-CORS policy mapping** and find the **most specific** endpoint that matches the blocked path — for example `app/<Alias>` takes precedence over `*`, so an allow-all `*` row does not help when a more specific row exists
+  - Open the CORS policy mapped to that endpoint and add the origin under **Allowed origins**
+  - The OAuth client registration's redirect URIs do not control this
+  - The browser may keep the old answer for the policy's **Maximum age**, so after the change use a hard refresh, a new private window, or wait that long
+
+  Say it in plain words, for example: "Your Pega server doesn't yet allow your app's address (`http://localhost:3000`) to talk to it. Ask your Pega administrator to add it under Allowed origins in the CORS policy for the `app/MediaCo` endpoint. Tell me when it's done and I'll carry on testing."
+
 - **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
+- Anything visual beyond the must-match and must-hold checks of Stage 4 assertions 10 and 11. Those checks are the only visual repairs this skill makes; everything else about how the form looks is reported, never forced
 
 ### 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.
+Fix, re-run the stage that failed, continue. Cap the number of repair cycles at three attempts per failing check. 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.
+
+### Stopping early
+
+Stop before Stage 4 has run only for one of these reasons, and always finish with the verification summary:
+
+- The Pega server is unreachable from this environment (Stage 2)
+- The Pega server does not allow this application's address — its CORS policy rejects the application's origin (Stage 2 preflight, or a CORS error after sign-in)
+- No browser can be used: the tool's own browser cannot follow the login popup and the user declined adding a browser automation library
+- The sign-in was not completed before the Stage 3 timeout
+- A report-only failure was reached, or the repair cap was exhausted
+
+Anything else — the run being long, many components, a stage needing a human for a moment — is not a reason to stop.
 
 ---
 
@@ -137,20 +196,21 @@ Fix, re-run the stage that failed, continue. Cap the number of repair cycles. On
 
 Always finish by reporting, whatever the outcome:
 
-- Which stages ran and which passed
+- Which stages ran and which passed — mark each stage **passed**, **fixed**, or **not run**, with the reason for any stage not run
 - 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_
+- The furthest stage reached, so "done" is never ambiguous between _generated_ and _verified_. If Stage 3 or Stage 4 did not run, say plainly "**Not verified yet**", give the reason from [Stopping early](#stopping-early), and say what the user can do next
 
 ---
 
 ## 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                                                         |
+| 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 files return not-found, or HTML                       | The configuration reference is relative and the launching route sits deeper than the application root, or the runtime files are not served at their absolute `/constellation/` URLs                                                                                                |
+| Initialization never completes, with no error                                  | The client identifier for the active login mode 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                                                                                                                                                                                                   |
+| Stuck on the loading state after sign-in, with a CORS error on a Pega API call | The Pega CORS policy for the most specific matching endpoint does not list the application's origin. Setting `appAlias` sends calls to `/app/<Alias>/api/...`, which can be mapped to a stricter policy than `/api/...`. A server setting — report it, never patch the application |