From ea62615a598b4ba10c60312c05785d1e1705c57c Mon Sep 17 00:00:00 2001
From: Michael Dailey <michael.dailey@provartesting.com>
Date: Wed, 22 Apr 2026 15:03:57 -0500
Subject: [PATCH 01/12] PDX-0: docs: add Provar test step reference and Copilot
 migration prompts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Req: Phase 2 corpus feature — canonical XML step reference bundled into MCP server and served as provar://docs/step-reference resource
Fix: Add PROVAR_TEST_STEP_REFERENCE.md with all step API IDs and three GitHub Copilot agent prompts for migration workflows

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/prompts/crt-to-provar.prompt.md       |   34 +
 .../prompts/playwright-to-provar.prompt.md    |   38 +
 .github/prompts/selenium-to-provar.prompt.md  |   35 +
 docs/PROVAR_TEST_STEP_REFERENCE.md            | 1337 +++++++++++++++++
 4 files changed, 1444 insertions(+)
 create mode 100644 .github/prompts/crt-to-provar.prompt.md
 create mode 100644 .github/prompts/playwright-to-provar.prompt.md
 create mode 100644 .github/prompts/selenium-to-provar.prompt.md
 create mode 100644 docs/PROVAR_TEST_STEP_REFERENCE.md

diff --git a/.github/prompts/crt-to-provar.prompt.md b/.github/prompts/crt-to-provar.prompt.md
new file mode 100644
index 00000000..c67efbad
--- /dev/null
+++ b/.github/prompts/crt-to-provar.prompt.md
@@ -0,0 +1,34 @@
+---
+mode: agent
+description: Convert a CRT (Copado Robotic Testing) test into a Provar XML test case using the Provar MCP tools for corpus grounding and validation
+---
+
+You are a Provar test migration expert. Migrate the CRT test below to Provar.
+
+## Source format — CRT
+
+CRT is a keyword-driven framework built on Robot Framework (QEditor-authored):
+
+- `ClickText <label>` → click an element by visible label
+- `TypeText <field> <value>` → type into a field
+- `VerifyText <text>` → assert text is present on the page
+- `SelectDropdown <field> <value>` → choose a picklist option
+- `OpenBrowser <url>` → open browser / Salesforce login
+
+Robot Framework sections: `*** Keywords ***` = reusable blocks, `*** Test Cases ***` = one file per test.
+
+## Migration workflow
+
+1. **Get examples** — call `provar.qualityhub.examples.retrieve` with keywords that describe the test scenario (e.g. "create account", "close opportunity"). Use the returned XML examples as the sole reference for Provar format and step patterns.
+2. **Generate** — produce valid Provar XML that captures the intent of the source test, based on the retrieved examples. Omit login/browser setup — Provar handles that via Connection Manager.
+3. **Write** — save the XML to the `tests/` directory in the Provar project.
+4. **Validate** — call `provar.testcase.validate` on the saved file. Fix any errors and re-validate until clean.
+5. **Report** — summarise what was migrated and flag any unmappable steps as `<!-- TODO: manual step — <original QWord> -->`.
+
+## CRT Source
+
+Paste your CRT test here (QWord steps or `.robot` file):
+
+```
+[PASTE CRT TEST HERE]
+```
diff --git a/.github/prompts/playwright-to-provar.prompt.md b/.github/prompts/playwright-to-provar.prompt.md
new file mode 100644
index 00000000..2984907e
--- /dev/null
+++ b/.github/prompts/playwright-to-provar.prompt.md
@@ -0,0 +1,38 @@
+---
+mode: agent
+description: Convert a Playwright test (TypeScript/JavaScript) into a Provar XML test case using the Provar MCP tools for corpus grounding and validation
+---
+
+You are a Provar test migration expert. Migrate the Playwright test below to Provar.
+
+## Source format — Playwright
+
+Common patterns to recognise:
+
+- `page.goto(url)` / login fixture → Salesforce login
+- `getByLabel(label).click()` → click by visible label
+- `getByRole('button', {name}).click()` → click by button name
+- `getByLabel(label).fill(value)` → fill a field by label
+- `locator(selector).fill(value)` → fill by XPath/CSS
+- `locator.selectOption(value)` → choose a picklist option
+- `expect(locator).toHaveValue(val)` → assert a field value
+- `expect(locator).toBeVisible()` → assert element is visible
+- `expect(page).toContainText(text)` → assert text on page
+- `page.waitForLoadState()` / `waitForSelector()` → wait conditions
+- `beforeEach` → test setup including login
+
+## Migration workflow
+
+1. **Get examples** — call `provar.qualityhub.examples.retrieve` with keywords describing the test scenario (e.g. "create contact", "close opportunity"). Use the returned XML examples as the sole reference for Provar format and step patterns.
+2. **Generate** — produce valid Provar XML based on the retrieved examples. Omit login/navigation setup — Provar handles Salesforce sessions via Connection Manager.
+3. **Write** — save the XML to the `tests/` directory in the Provar project.
+4. **Validate** — call `provar.testcase.validate` on the saved file. Fix any errors and re-validate until clean.
+5. **Report** — summarise what was migrated and flag any unmappable steps as `<!-- TODO: manual step — <original code> -->`.
+
+## Playwright Source
+
+Paste your Playwright test here (TypeScript or JavaScript):
+
+```typescript
+[PASTE PLAYWRIGHT TEST HERE]
+```
diff --git a/.github/prompts/selenium-to-provar.prompt.md b/.github/prompts/selenium-to-provar.prompt.md
new file mode 100644
index 00000000..3a46422c
--- /dev/null
+++ b/.github/prompts/selenium-to-provar.prompt.md
@@ -0,0 +1,35 @@
+---
+mode: agent
+description: Convert a Selenium WebDriver test (Java/Python/JS) into a Provar XML test case using the Provar MCP tools for corpus grounding and validation
+---
+
+You are a Provar test migration expert. Migrate the Selenium test below to Provar.
+
+## Source format — Selenium WebDriver
+
+Common patterns to recognise:
+
+- `driver.get(url)` / `navigate().to()` → Salesforce login
+- `findElement(By.linkText/name).click()` → click by visible label
+- `findElement(...).sendKeys(value)` → type into a field
+- `Select.selectByVisibleText(val)` → choose a picklist option
+- `findElement(...).getText()` + assertion → verify a field value
+- `WebDriverWait` / `ExpectedConditions` → wait for element
+- `@Before` / `setUp()` → test setup including login
+- `@After` / `tearDown()` → cleanup
+
+## Migration workflow
+
+1. **Get examples** — call `provar.qualityhub.examples.retrieve` with keywords describing the test scenario (e.g. "create opportunity", "convert lead"). Use the returned XML examples as the sole reference for Provar format and step patterns.
+2. **Generate** — produce valid Provar XML based on the retrieved examples. Omit browser/login setup — Provar handles Salesforce sessions via Connection Manager.
+3. **Write** — save the XML to the `tests/` directory in the Provar project.
+4. **Validate** — call `provar.testcase.validate` on the saved file. Fix any errors and re-validate until clean.
+5. **Report** — summarise what was migrated and flag any unmappable steps as `<!-- TODO: manual step — <original code> -->`.
+
+## Selenium Source
+
+Paste your Selenium test here (Java, Python, or JavaScript):
+
+```
+[PASTE SELENIUM TEST HERE]
+```
diff --git a/docs/PROVAR_TEST_STEP_REFERENCE.md b/docs/PROVAR_TEST_STEP_REFERENCE.md
new file mode 100644
index 00000000..eb813c95
--- /dev/null
+++ b/docs/PROVAR_TEST_STEP_REFERENCE.md
@@ -0,0 +1,1337 @@
+# Provar Test Step Reference
+
+> **Source of truth** for AI-assisted test generation in the provardx-cli / Quality Hub MCP toolchain.
+> All examples are sourced from the SalesCloud corpus. The `provar.qualityhub.examples.retrieve` tool returns real
+> examples for additional grounding; `provar.testcase.validate` enforces all rules documented here.
+
+---
+
+## API ID Reference
+
+| Step Type             | API ID                                                                   |
+| --------------------- | ------------------------------------------------------------------------ |
+| **Connection**        |                                                                          |
+| ApexConnect           | `com.provar.plugins.forcedotcom.core.testapis.ApexConnect`               |
+| UiConnect             | `com.provar.plugins.forcedotcom.core.ui.UiConnect`                       |
+| **Apex CRUD**         |                                                                          |
+| ApexCreateObject      | `com.provar.plugins.forcedotcom.core.testapis.ApexCreateObject`          |
+| ApexReadObject        | `com.provar.plugins.forcedotcom.core.testapis.ApexReadObject`            |
+| ApexUpdateObject      | `com.provar.plugins.forcedotcom.core.testapis.ApexUpdateObject`          |
+| ApexDeleteObject      | `com.provar.plugins.forcedotcom.core.testapis.ApexDeleteObject`          |
+| ApexSoqlQuery         | `com.provar.plugins.forcedotcom.core.testapis.ApexSoqlQuery`             |
+| **Apex Advanced**     |                                                                          |
+| ApexBulk              | `com.provar.plugins.forcedotcom.core.testapis.ApexBulk`                  |
+| ApexExecute           | `com.provar.plugins.forcedotcom.core.testapis.ApexExecute`               |
+| ApexConvertLead       | `com.provar.plugins.forcedotcom.core.testapis.ApexConvertLead`           |
+| ApexExtractLayout     | `com.provar.plugins.forcedotcom.core.testapis.ApexExtractLayout`         |
+| ApexAssertLayout      | `com.provar.plugins.forcedotcom.core.testapis.ApexAssertLayout`          |
+| ApexApproveWorkItem   | `com.provar.plugins.forcedotcom.core.testapis.ApexApproveWorkItem`       |
+| ApexSubmitForApproval | `com.provar.plugins.forcedotcom.core.testapis.ApexSubmitForApproval`     |
+| ApexLogForCleanup     | `com.provar.plugins.forcedotcom.core.testapis.ApexLogForCleanup`         |
+| **UI Steps**          |                                                                          |
+| UiWithScreen          | `com.provar.plugins.forcedotcom.core.ui.UiWithScreen`                    |
+| UiDoAction            | `com.provar.plugins.forcedotcom.core.ui.UiDoAction`                      |
+| UiAssert              | `com.provar.plugins.forcedotcom.core.ui.UiAssert`                        |
+| UiWithRow             | `com.provar.plugins.forcedotcom.core.ui.UiWithRow`                       |
+| UiHandleAlert         | `com.provar.plugins.forcedotcom.core.ui.UiHandleAlert`                   |
+| UiNavigate            | `com.provar.plugins.forcedotcom.core.ui.UiNavigate`                      |
+| **Control Flow**      |                                                                          |
+| SetValues             | `com.provar.plugins.bundled.apis.control.SetValues`                      |
+| StepGroup             | `com.provar.plugins.bundled.apis.control.StepGroup`                      |
+| If                    | `com.provar.plugins.bundled.apis.If`                                     |
+| ForEach               | `com.provar.plugins.bundled.apis.control.ForEach`                        |
+| DoWhile               | `com.provar.plugins.bundled.apis.control.DoWhile`                        |
+| WaitFor               | `com.provar.plugins.bundled.apis.control.WaitFor`                        |
+| TryCatchFinally       | `com.provar.plugins.bundled.apis.control.TryCatchFinally`                |
+| Switch                | `com.provar.plugins.bundled.apis.Switch`                                 |
+| Sleep                 | `com.provar.plugins.bundled.apis.control.Sleep`                          |
+| Fail                  | `com.provar.plugins.bundled.apis.control.Fail`                           |
+| CallTest              | `com.provar.plugins.bundled.apis.control.CallTest`                       |
+| **Assertions**        |                                                                          |
+| AssertValues          | `com.provar.plugins.bundled.apis.AssertValues`                           |
+| **BDD**               |                                                                          |
+| Given                 | `com.provar.plugins.bundled.apis.bdd.Given`                              |
+| When                  | `com.provar.plugins.bundled.apis.bdd.When`                               |
+| Then                  | `com.provar.plugins.bundled.apis.bdd.Then`                               |
+| And                   | `com.provar.plugins.bundled.apis.bdd.And`                                |
+| But                   | `com.provar.plugins.bundled.apis.bdd.But`                                |
+| **Design**            |                                                                          |
+| ActualResult          | `com.provar.plugins.bundled.apis.control.ActualResult`                   |
+| DesignStep            | `com.provar.plugins.bundled.apis.control.DesignStep`                     |
+| **Database**          |                                                                          |
+| DbConnect             | `com.provar.plugins.bundled.apis.db.DbConnect`                           |
+| DbRead                | `com.provar.plugins.bundled.apis.db.DbRead`                              |
+| DbInsert              | `com.provar.plugins.bundled.apis.db.DbInsert`                            |
+| DbUpdate              | `com.provar.plugins.bundled.apis.db.DbUpdate`                            |
+| DbDelete              | `com.provar.plugins.bundled.apis.db.DbDelete`                            |
+| SqlQuery              | `com.provar.plugins.bundled.apis.db.SqlQuery`                            |
+| **Web Service**       |                                                                          |
+| WebConnect            | `com.provar.plugins.bundled.apis.restservice.WebConnect`                 |
+| RestRequest           | `com.provar.plugins.bundled.apis.restservice.RestRequest`                |
+| SoapRequest           | `com.provar.plugins.bundled.apis.restservice.SoapRequest`                |
+| **Messaging**         |                                                                          |
+| PublishMessage        | `com.provar.plugins.bundled.apis.messaging.PublishMessage`               |
+| Subscribe             | `com.provar.plugins.bundled.apis.messaging.Subscribe`                    |
+| ReceiveMessage        | `com.provar.plugins.bundled.apis.messaging.ReceiveMessage`               |
+| SendMessage           | `com.provar.plugins.bundled.apis.messaging.SendMessage`                  |
+| **Utility**           |                                                                          |
+| ListCompare           | `com.provar.plugins.bundled.apis.list.ListCompare`                       |
+| Match                 | `com.provar.plugins.bundled.apis.string.Match`                           |
+| Read                  | `com.provar.plugins.bundled.apis.io.Read`                                |
+| Write                 | `com.provar.plugins.bundled.apis.io.Write`                               |
+| Split                 | `com.provar.plugins.bundled.apis.string.Split`                           |
+| Replace               | `com.provar.plugins.bundled.apis.string.Replace`                         |
+| **ProvarAI / Labs**   |                                                                          |
+| GenerateTestData      | `com.provar.plugins.forcedotcom.core.testapis.generate.GenerateTestData` |
+| GenerateTestCase      | `com.provar.plugins.forcedotcom.core.testapis.GenerateTestCase`          |
+| PageObjectCleaner     | `com.provar.plugins.bundled.apis.provarlabs.PageObjectCleaner`           |
+
+---
+
+## Common AI Hallucinations — Do Not Use
+
+The following argument IDs look plausible but are invalid and will fail validation:
+
+| Invalid argument              | Correct alternative                                        |
+| ----------------------------- | ---------------------------------------------------------- |
+| `autoPopulateRequiredFields`  | Not supported — populate fields explicitly                 |
+| `assertObjectFieldsPopulated` | Use `UiAssert` or `ApexReadObject` instead                 |
+| `commandTimeout`              | Not a valid argument on any step                           |
+| `waitForPageLoad`             | Use `beforeWait`/`afterWait` with `uiWait` URI             |
+| `screenshotOnFailure`         | Use `captureBefore`/`captureAfter` (string "true"/"false") |
+| `closeAllOtherTabs`           | The correct id is `closeAllPrimaryTabs` (ApexConnect only) |
+| `connectionType`              | Not a step argument; connection type is implied by apiId   |
+
+---
+
+## Connection Steps
+
+### ApexConnect
+
+Establishes a Salesforce connection (API + optional UI). Usually the first step in every test. Use `autoCleanup="true"` to automatically log out after the test; omit it only when you want the connection to persist into a parent scope.
+
+> **`connectionId` must use `valueClass="id"`** (a GUID string), not `valueClass="string"`. The validator
+> enforces this (rule APEX-CONNECT-CONNID-001).
+
+> **ApexConnect vs UiConnect:** ApexConnect opens both an API connection and (optionally) a UI browser session.
+> UiConnect opens only a browser session, using an existing ApexConnect result as its Salesforce credential.
+> In most test cases you need only ApexConnect.
+
+```xml
+<apiCall apiId="com.provar.plugins.forcedotcom.core.testapis.ApexConnect"
+         name="ApexConnect" testItemId="1"
+         title="Salesforce Connect: SalesUser (Test)">
+  <arguments>
+    <argument id="connectionName">
+      <value class="value" valueClass="string">SalesUser</value>
+    </argument>
+    <argument id="connectionId">
+      <value class="value" valueClass="id">74c34c63-ad34-43d9-bb12-cd783bd9bcdd</value>
+    </argument>
+    <argument id="resultName">
+      <value class="value" valueClass="string">DemoOrg</value>
+    </argument>
+    <argument id="resultScope">
+      <value class="value" valueClass="string">Test</value>
+    </argument>
+    <argument id="uiApplicationName">
+      <value class="value" valueClass="string">LightningSales</value>
+    </argument>
+    <argument id="quickUiLogin">
+      <value class="value" valueClass="boolean">true</value>
+    </argument>
+    <argument id="closeAllPrimaryTabs">
+      <value class="value" valueClass="boolean">true</value>
+    </argument>
+    <argument id="reuseConnectionName"/>
+    <argument id="alreadyOpenBehaviour">
+      <value class="value" valueClass="string">Fail</value>
+    </argument>
+    <argument id="privateBrowsingMode"/>
+    <argument id="enableObjectIdLogging">
+      <value class="value" valueClass="boolean">true</value>
+    </argument>
+    <argument id="autoCleanup">
+      <value class="value" valueClass="boolean">true</value>
+    </argument>
+    <argument id="cleanupConnectionName"/>
+    <argument id="lightningMode">
+      <value class="value" valueClass="string">enable</value>
+    </argument>
+    <argument id="webBrowser"/>
+  </arguments>
+</apiCall>
+```
+
+**Valid `alreadyOpenBehaviour` values:** `Reuse` | `Fail`
+**Valid `lightningMode` values:** `enable` | `default`
+**Valid `resultScope` values:** `Test` | `Global` | `Folder`
+
+### UiConnect
+
+Opens a browser-only UI session. Use this when you have a separate ApexConnect for API operations and need an independent browser window. Fewer arguments than ApexConnect — it does not manage Salesforce API credentials.
+
+> **UiConnect does NOT accept:** `autoCleanup`, `enableObjectIdLogging`, `quickUiLogin`, `closeAllPrimaryTabs`,
+> `alreadyOpenBehaviour`, `lightningMode`, `uiApplicationName`, `cleanupConnectionName`.
+> Using these on UiConnect will fail validation (rule UI-CONNECT-ARGS-001).
+
+```xml
+<apiCall apiId="com.provar.plugins.forcedotcom.core.ui.UiConnect"
+         name="UiConnect" testItemId="1"
+         title="UI Connect: DemoOrg">
+  <arguments>
+    <argument id="connectionName">
+      <value class="value" valueClass="string">DemoOrg</value>
+    </argument>
+    <argument id="resultName">
+      <value class="value" valueClass="string">DemoOrg</value>
+    </argument>
+    <argument id="resultScope">
+      <value class="value" valueClass="string">Test</value>
+    </argument>
+    <argument id="reuseConnectionName"/>
+    <argument id="privateBrowsingMode"/>
+    <argument id="webBrowser"/>
+  </arguments>
+</apiCall>
+```
+
+---
+
+## UI Steps
+
+UI steps must always be nested inside a `UiWithScreen` block. Never place `UiDoAction` or `UiAssert` directly in the top-level `<steps>` list.
+
+### UiWithScreen
+
+Navigates to (or asserts presence of) a Salesforce screen, then runs substeps against it. All UI actions and assertions go inside the `<clause name="substeps">` block.
+
+**Navigation rules:**
+
+- The first `UiWithScreen` in a test **must** use `navigate="Always"` or `navigate="IfNecessary"`. Never `"Dont"` for the first screen.
+- Subsequent screens in the same flow should use `navigate="Dont"` when Salesforce has already navigated there (e.g., after clicking Save the record view is already open).
+- `navigate="Always"` on an `Edit` or `View` action **requires** `sfUiTargetObjectId` (the record ID). Without it, Provar cannot navigate to the correct record.
+- `sfUiTargetResultName` captures the record ID that Salesforce creates (useful on `New` action screens after save).
+
+**Target URI format:** `sf:ui:target?object=OBJECT&action=ACTION`
+
+Valid `action` values: `ObjectHome` | `New` | `View` | `Edit` | `Delete` | `Clone`
+
+```xml
+<!-- First screen: navigate=Always required -->
+<apiCall apiId="com.provar.plugins.forcedotcom.core.ui.UiWithScreen"
+         name="UiWithScreen" testItemId="2"
+         title="On SF Opportunity Home screen">
+  <arguments>
+    <argument id="uiConnectionName">
+      <value class="value" valueClass="string">DemoOrg</value>
+    </argument>
+    <argument id="target">
+      <value class="uiTarget" uri="sf:ui:target?object=Opportunity&amp;action=ObjectHome"/>
+    </argument>
+    <argument id="navigate">
+      <value class="value" valueClass="string">Always</value>
+    </argument>
+    <argument id="targetDescription">
+      <value class="value" valueClass="string">On SF Opportunity Home screen</value>
+    </argument>
+    <argument id="windowSelection">
+      <value class="value" valueClass="string">Default</value>
+    </argument>
+    <argument id="windowSize">
+      <value class="value" valueClass="string">Default</value>
+    </argument>
+    <argument id="closeWindow"/>
+    <argument id="captureBefore">
+      <value class="value" valueClass="string">false</value>
+    </argument>
+    <argument id="captureAfter">
+      <value class="value" valueClass="string">false</value>
+    </argument>
+  </arguments>
+  <clauses>
+    <clause name="substeps" testItemId="3">
+      <steps>
+        <!-- UiDoAction and UiAssert steps go here -->
+      </steps>
+    </clause>
+  </clauses>
+</apiCall>
+
+<!-- New screen: navigate=Dont (already arrived via New button click), capture resulting record ID -->
+<apiCall apiId="com.provar.plugins.forcedotcom.core.ui.UiWithScreen"
+         name="UiWithScreen" testItemId="5"
+         title="On SF Opportunity New screen">
+  <arguments>
+    <argument id="uiConnectionName">
+      <value class="value" valueClass="string">DemoOrg</value>
+    </argument>
+    <argument id="target">
+      <value class="uiTarget" uri="sf:ui:target?object=Opportunity&amp;noOverride=true&amp;action=New"/>
+    </argument>
+    <argument id="navigate">
+      <value class="value" valueClass="string">Dont</value>
+    </argument>
+    <argument id="targetDescription">
+      <value class="value" valueClass="string">On SF Opportunity New screen</value>
+    </argument>
+    <argument id="windowSelection">
+      <value class="value" valueClass="string">Default</value>
+    </argument>
+    <argument id="windowSize">
+      <value class="value" valueClass="string">Default</value>
+    </argument>
+    <argument id="closeWindow"/>
+    <argument id="captureBefore">
+      <value class="value" valueClass="string">false</value>
+    </argument>
+    <argument id="captureAfter">
+      <value class="value" valueClass="string">false</value>
+    </argument>
+    <argument id="sfUiTargetResultName">
+      <value class="value" valueClass="string">opportunityId</value>
+    </argument>
+    <argument id="sfUiTargetResultScope">
+      <value class="value" valueClass="string">Test</value>
+    </argument>
+  </arguments>
+  <clauses>
+    <clause name="substeps" testItemId="6">
+      <steps>
+        <!-- fill fields, then Save -->
+      </steps>
+    </clause>
+  </clauses>
+</apiCall>
+
+<!-- View screen: navigate=Always requires sfUiTargetObjectId -->
+<apiCall apiId="com.provar.plugins.forcedotcom.core.ui.UiWithScreen"
+         name="UiWithScreen" testItemId="12"
+         title="On SF Opportunity View screen">
+  <arguments>
+    <argument id="uiConnectionName">
+      <value class="value" valueClass="string">DemoOrg</value>
+    </argument>
+    <argument id="target">
+      <value class="uiTarget" uri="sf:ui:target?object=Opportunity&amp;noOverride=true&amp;action=View"/>
+    </argument>
+    <argument id="navigate">
+      <value class="value" valueClass="string">Always</value>
+    </argument>
+    <argument id="targetDescription">
+      <value class="value" valueClass="string">On SF Opportunity View screen</value>
+    </argument>
+    <argument id="windowSelection">
+      <value class="value" valueClass="string">Default</value>
+    </argument>
+    <argument id="windowSize">
+      <value class="value" valueClass="string">Default</value>
+    </argument>
+    <argument id="closeWindow"/>
+    <argument id="captureBefore">
+      <value class="value" valueClass="string">false</value>
+    </argument>
+    <argument id="captureAfter">
+      <value class="value" valueClass="string">false</value>
+    </argument>
+    <argument id="sfUiTargetObjectId">
+      <value class="variable">
+        <path element="opportunityId"/>
+      </value>
+    </argument>
+  </arguments>
+  <clauses>
+    <clause name="substeps" testItemId="13">
+      <steps>
+        <!-- UiAssert steps go here -->
+      </steps>
+    </clause>
+  </clauses>
+</apiCall>
+```
+
+### UiDoAction
+
+Performs a single UI interaction on a field or button. The `interaction` URI determines the action type.
+
+**Interaction types:**
+
+- `ui:interaction?name=action` — click a button or link
+- `ui:interaction?name=set` — fill/type into a field or select a picklist value
+- `ui:interaction?name=file` — upload a file (uses `fileLocation` instead of `value`)
+
+**Locator URI format:** `ui:locator?name=FIELD_OR_BUTTON_NAME&binding=ENCODED_BINDING`
+
+The binding component URL-encodes `sf:ui:binding:object?object=OBJECT&field=FIELD` for field locators, or `sf:ui:binding:object?object=OBJECT&action=ACTION` for action locators.
+
+```xml
+<!-- Click a button (interaction=action) -->
+<apiCall apiId="com.provar.plugins.forcedotcom.core.ui.UiDoAction"
+         name="UiDoAction" testItemId="4"
+         title="Click the New button">
+  <arguments>
+    <argument id="locator">
+      <value class="uiLocator" uri="ui:locator?name=New&amp;binding=sf%3Aui%3Abinding%3Aobject%3Fobject%3DOpportunity%26action%3DNew"/>
+    </argument>
+    <argument id="interaction">
+      <value class="uiInteraction" uri="ui:interaction?name=action"/>
+    </argument>
+    <argument id="hover">
+      <value class="value" valueClass="boolean">false</value>
+    </argument>
+    <argument id="captureBefore">
+      <value class="value" valueClass="string">false</value>
+    </argument>
+    <argument id="captureAfter">
+      <value class="value" valueClass="string">false</value>
+    </argument>
+    <argument id="beforeWait">
+      <value class="uiWait" uri="default"/>
+    </argument>
+    <argument id="afterWait">
+      <value class="uiWait" uri="default"/>
+    </argument>
+    <argument id="interactionDescription">
+      <value class="value" valueClass="string">Click the New button</value>
+    </argument>
+    <argument id="autoRetry"/>
+  </arguments>
+</apiCall>
+
+<!-- Set a text/picklist field (interaction=set) -->
+<apiCall apiId="com.provar.plugins.forcedotcom.core.ui.UiDoAction"
+         name="UiDoAction" testItemId="7"
+         title="Set the Opportunity Name field to Test">
+  <arguments>
+    <argument id="locator">
+      <value class="uiLocator" uri="ui:locator?name=Name&amp;binding=sf%3Aui%3Abinding%3Aobject%3Fobject%3DOpportunity%26field%3DName"/>
+    </argument>
+    <argument id="interaction">
+      <value class="uiInteraction" uri="ui:interaction?name=set"/>
+    </argument>
+    <argument id="value">
+      <value class="value" valueClass="string">Test</value>
+    </argument>
+    <argument id="blur">
+      <value class="value" valueClass="boolean">false</value>
+    </argument>
+    <argument id="pressEnter">
+      <value class="value" valueClass="boolean">false</value>
+    </argument>
+    <argument id="captureBefore">
+      <value class="value" valueClass="string">false</value>
+    </argument>
+    <argument id="captureAfter">
+      <value class="value" valueClass="string">false</value>
+    </argument>
+    <argument id="beforeWait">
+      <value class="uiWait" uri="default"/>
+    </argument>
+    <argument id="afterWait">
+      <value class="uiWait" uri="default"/>
+    </argument>
+    <argument id="interactionDescription">
+      <value class="value" valueClass="string">Set the Opportunity Name field to Test</value>
+    </argument>
+    <argument id="autoRetry"/>
+  </arguments>
+</apiCall>
+
+<!-- Upload a file (interaction=file) -->
+<apiCall apiId="com.provar.plugins.forcedotcom.core.ui.UiDoAction"
+         name="UiDoAction" testItemId="15"
+         title="Upload attachment file">
+  <arguments>
+    <argument id="locator">
+      <value class="uiLocator" uri="ui:locator?name=AttachFile&amp;binding=sf%3Aui%3Abinding%3Aobject%3Fobject%3DOpportunity%26action%3DAttachFile%26relationship%3DCombinedAttachments"/>
+    </argument>
+    <argument id="interaction">
+      <value class="uiInteraction" uri="ui:interaction?name=file"/>
+    </argument>
+    <argument id="fileLocation">
+      <value class="value" valueClass="string">templates/TestData.xlsx</value>
+    </argument>
+    <argument id="fileContents"/>
+    <argument id="captureBefore">
+      <value class="value" valueClass="string">false</value>
+    </argument>
+    <argument id="captureAfter">
+      <value class="value" valueClass="string">false</value>
+    </argument>
+    <argument id="beforeWait">
+      <value class="uiWait" uri="default"/>
+    </argument>
+    <argument id="afterWait">
+      <value class="uiWait" uri="default"/>
+    </argument>
+    <argument id="interactionDescription">
+      <value class="value" valueClass="string">Upload attachment file</value>
+    </argument>
+    <argument id="autoRetry">
+      <value class="uiWait" uri="ui:wait:autoRetry:timeout=10"/>
+    </argument>
+  </arguments>
+</apiCall>
+```
+
+> **Rule UI-DOACTION-VALUE-001:** When `interaction` is `set`, the `value` argument is required.
+> When `interaction` is `action`, the `value` argument must be absent.
+
+### UiAssert
+
+Verifies field values or element state on the current screen. Must always include `columnAssertions`, `pageAssertions`, `resultScope`, `captureAfter`, `beforeWait`, and `autoRetry` — even when empty.
+
+> **Rule UI-ASSERT-STRUCT-001:** All six arguments above are required. Omitting any will fail validation.
+>
+> **Rule UI-ASSERT-STRUCT-002:** Do NOT include `generatedParameters` on `UiAssert`. Unlike `UiDoAction`,
+> `UiAssert` does not use `generatedParameters` for its field assertions.
+>
+> **Rule UI-ASSERT-FIELDLOCATOR-002:** The `uiFieldAssertion` uses a bare `<fieldLocator uri="..."/>` element,
+> NOT a `<value class="uiLocator">` wrapper.
+
+```xml
+<!-- Assert a field value -->
+<apiCall apiId="com.provar.plugins.forcedotcom.core.ui.UiAssert"
+         name="UiAssert" testItemId="14"
+         title="UI Assert: Name">
+  <arguments>
+    <argument id="resultName">
+      <value class="value" valueClass="string">Values</value>
+    </argument>
+    <argument id="resultScope">
+      <value class="value" valueClass="string">Test</value>
+    </argument>
+    <argument id="fieldAssertions">
+      <value class="valueList" mutable="Mutable">
+        <uiFieldAssertion resultName="Name">
+          <fieldLocator uri="ui:locator?name=Name&amp;binding=sf%3Aui%3Abinding%3Aobject%3Fobject%3DOpportunity%26field%3DName"/>
+          <attributeAssertions>
+            <uiAttributeAssertion attributeName="value" comparisonType="EqualTo" normalize="true">
+              <value class="value" valueClass="string">Test</value>
+            </uiAttributeAssertion>
+          </attributeAssertions>
+        </uiFieldAssertion>
+      </value>
+    </argument>
+    <argument id="captureAfter">
+      <value class="value" valueClass="string">false</value>
+    </argument>
+    <argument id="columnAssertions">
+      <value class="valueList" mutable="Mutable"/>
+    </argument>
+    <argument id="pageAssertions">
+      <value class="valueList" mutable="Mutable"/>
+    </argument>
+    <argument id="beforeWait"/>
+    <argument id="autoRetry"/>
+  </arguments>
+</apiCall>
+
+<!-- Assert a related list row count -->
+<apiCall apiId="com.provar.plugins.forcedotcom.core.ui.UiAssert"
+         name="UiAssert" testItemId="16"
+         title="UI Assert: Attachment count">
+  <arguments>
+    <argument id="resultName">
+      <value class="value" valueClass="string">Values</value>
+    </argument>
+    <argument id="resultScope">
+      <value class="value" valueClass="string">Test</value>
+    </argument>
+    <argument id="fieldAssertions">
+      <value class="valueList" mutable="Mutable">
+        <uiFieldAssertion resultName="CombinedAttachments">
+          <fieldLocator uri="ui:locator?name=CombinedAttachments&amp;binding=sf%3Aui%3Abinding%3Aobject%3Fobject%3DOpportunity%26relationship%3DCombinedAttachments"/>
+          <attributeAssertions>
+            <uiAttributeAssertion attributeName="totalRowCount" comparisonType="EqualTo">
+              <value class="value" valueClass="string">1</value>
+            </uiAttributeAssertion>
+            <uiAttributeAssertion attributeName="value" comparisonType="None"/>
+          </attributeAssertions>
+        </uiFieldAssertion>
+      </value>
+    </argument>
+    <argument id="captureAfter">
+      <value class="value" valueClass="string">false</value>
+    </argument>
+    <argument id="columnAssertions">
+      <value class="valueList" mutable="Mutable"/>
+    </argument>
+    <argument id="pageAssertions">
+      <value class="valueList" mutable="Mutable"/>
+    </argument>
+    <argument id="beforeWait"/>
+    <argument id="autoRetry"/>
+  </arguments>
+</apiCall>
+```
+
+**Valid `comparisonType` values:** `EqualTo` | `NotEqualTo` | `Contains` | `NotContains` | `StartsWith` | `EndsWith` | `None`
+
+### UiWithRow
+
+Targets a specific row in a related list or table. Substeps inside the clause operate in the row context (locators can use `rowLocator` parameter for scoping).
+
+```xml
+<apiCall apiId="com.provar.plugins.forcedotcom.core.ui.UiWithRow"
+         name="UiWithRow" testItemId="22"
+         title="With Roles rows 1">
+  <arguments>
+    <argument id="uiConnectionName">
+      <value class="value" valueClass="string">DemoOrg</value>
+    </argument>
+    <argument id="locator">
+      <value class="uiLocator" uri="sf:ui:locator:row?table=roleBlock%2Froles"/>
+    </argument>
+    <argument id="uiRowLocator">
+      <value class="value" valueClass="string">1</value>
+    </argument>
+    <argument id="locatorDescription">
+      <value class="value" valueClass="string">With Roles rows 1</value>
+    </argument>
+    <argument id="failIfNotFound">
+      <value class="value" valueClass="boolean">true</value>
+    </argument>
+    <argument id="debugRowLocator">
+      <value class="value" valueClass="boolean">true</value>
+    </argument>
+    <argument id="resultName">
+      <value class="value" valueClass="string">Row</value>
+    </argument>
+    <argument id="resultScope">
+      <value class="value" valueClass="string">Local</value>
+    </argument>
+  </arguments>
+  <clauses>
+    <clause name="substeps" testItemId="23">
+      <steps>
+        <!-- UiDoAction steps scoped to this row -->
+      </steps>
+    </clause>
+  </clauses>
+</apiCall>
+```
+
+**Row locator URI format:** `sf:ui:locator:row?table=RELATED_LIST_NAME`
+
+The `uiRowLocator` can be a row number (1-based) or a field-value match expression.
+
+### UiHandleAlert
+
+Handles browser-level alert/confirm dialogs. Place this immediately after the step that triggers the dialog (e.g., a Delete button click).
+
+```xml
+<apiCall apiId="com.provar.plugins.forcedotcom.core.ui.UiHandleAlert"
+         name="UiHandleAlert" testItemId="46"
+         title="Handle UI Alerts">
+  <arguments>
+    <argument id="alerts">
+      <value class="valueList" mutable="Mutable">
+        <namedValues mutable="Mutable">
+          <namedValue name="expectedMessage"/>
+          <namedValue name="response">
+            <value class="value" valueClass="string">OK</value>
+          </namedValue>
+          <namedValue name="beforeWait"/>
+          <namedValue name="afterWait"/>
+          <namedValue name="autoRetry"/>
+        </namedValues>
+      </value>
+    </argument>
+    <argument id="captureBefore">
+      <value class="value" valueClass="string">false</value>
+    </argument>
+    <argument id="captureAfter">
+      <value class="value" valueClass="string">false</value>
+    </argument>
+  </arguments>
+</apiCall>
+```
+
+**Valid `response` values:** `OK` | `Cancel`
+
+Set `expectedMessage` to a string value to assert the alert text matches before responding.
+
+---
+
+## Apex CRUD Operations
+
+### ApexCreateObject
+
+Creates a Salesforce record via the API. Requires `parameterGeneratorUri`, `parameterGeneratorProperties`, and `generatedParameters` — these are always present on Apex CRUD steps and the validator checks for them.
+
+> **`parameterGeneratorProperties` key format:** The full command class name prefix is required, e.g.
+> `com.provar.plugins.forcedotcom.ui.commands.CreateCustomObjectTestStepCommand.ConnectionName`
+> (not just `.ConnectionName`).
+
+```xml
+<apiCall apiId="com.provar.plugins.forcedotcom.core.testapis.ApexCreateObject"
+         name="ApexCreateObject"
+         parameterGeneratorUri="command:com.provar.plugins.forcedotcom.ui.commands.CreateCustomObjectTestStepCommand"
+         testItemId="3"
+         title="Create Object: Lead=&gt;LeadId">
+  <arguments>
+    <argument id="objectType">
+      <value class="value" valueClass="string">Lead</value>
+    </argument>
+    <argument id="resultIdName">
+      <value class="value" valueClass="string">LeadId</value>
+    </argument>
+    <argument id="apexConnectionName">
+      <value class="value" valueClass="string">Admin</value>
+    </argument>
+    <argument id="resultScope">
+      <value class="value" valueClass="string">Test</value>
+    </argument>
+    <argument id="LastName">
+      <value class="value" valueClass="string">Smith</value>
+    </argument>
+    <argument id="Company">
+      <value class="value" valueClass="string">Acme</value>
+    </argument>
+  </arguments>
+  <parameterGeneratorProperties>
+    <propertyValue name="com.provar.plugins.forcedotcom.ui.commands.CreateCustomObjectTestStepCommand.ConnectionName">Admin</propertyValue>
+    <propertyValue name="com.provar.plugins.forcedotcom.ui.commands.CreateCustomObjectTestStepCommand.CustomObjectName">Lead</propertyValue>
+  </parameterGeneratorProperties>
+  <generatedParameters>
+    <apiParam group="fields" modelBinding="sf:ui:binding:object?object=Lead&amp;field=LastName" name="LastName" title="LastName"/>
+    <apiParam group="fields" modelBinding="sf:ui:binding:object?object=Lead&amp;field=Company" name="Company" title="Company"/>
+  </generatedParameters>
+</apiCall>
+```
+
+### ApexReadObject
+
+Reads fields from an existing record by ID. `objectId` takes a variable reference to an ID stored from a prior `ApexCreateObject` or `sfUiTargetResultName` capture.
+
+```xml
+<apiCall apiId="com.provar.plugins.forcedotcom.core.testapis.ApexReadObject"
+         name="ApexReadObject"
+         parameterGeneratorUri="command:com.provar.plugins.forcedotcom.ui.commands.ReadCustomObjectTestStepCommand"
+         testItemId="1"
+         title="Read Object: Account = {AccountId}">
+  <arguments>
+    <argument id="apexConnectionName">
+      <value class="value" valueClass="string">Admin</value>
+    </argument>
+    <argument id="objectType">
+      <value class="value" valueClass="string">Account</value>
+    </argument>
+    <argument id="objectId">
+      <value class="variable">
+        <path element="AccountId"/>
+      </value>
+    </argument>
+    <argument id="resultName">
+      <value class="value" valueClass="string">AccountRecord</value>
+    </argument>
+  </arguments>
+  <parameterGeneratorProperties>
+    <propertyValue name="com.provar.plugins.forcedotcom.ui.commands.ReadCustomObjectTestStepCommand.ConnectionName">Admin</propertyValue>
+    <propertyValue name="com.provar.plugins.forcedotcom.ui.commands.ReadCustomObjectTestStepCommand.CustomObjectName">Account</propertyValue>
+  </parameterGeneratorProperties>
+  <generatedParameters>
+    <apiParam group="fields" modelBinding="sf:ui:binding:object?object=Account&amp;field=Name" name="Name" title="Name"/>
+    <apiParam group="fields" modelBinding="sf:ui:binding:object?object=Account&amp;field=Phone" name="Phone" title="Phone"/>
+  </generatedParameters>
+</apiCall>
+```
+
+### ApexUpdateObject
+
+Updates fields on an existing record. `objectId` is required and must reference a variable.
+
+```xml
+<apiCall apiId="com.provar.plugins.forcedotcom.core.testapis.ApexUpdateObject"
+         name="ApexUpdateObject"
+         parameterGeneratorUri="command:com.provar.plugins.forcedotcom.ui.commands.UpdateCustomObjectTestStepCommand"
+         testItemId="1"
+         title="Update Object: Account = {AccountId}">
+  <arguments>
+    <argument id="apexConnectionName">
+      <value class="value" valueClass="string">Admin</value>
+    </argument>
+    <argument id="objectType">
+      <value class="value" valueClass="string">Account</value>
+    </argument>
+    <argument id="objectId">
+      <value class="variable">
+        <path element="AccountId"/>
+      </value>
+    </argument>
+    <argument id="Industry">
+      <value class="value" valueClass="string">Technology</value>
+    </argument>
+  </arguments>
+  <parameterGeneratorProperties>
+    <propertyValue name="com.provar.plugins.forcedotcom.ui.commands.UpdateCustomObjectTestStepCommand.ConnectionName">Admin</propertyValue>
+    <propertyValue name="com.provar.plugins.forcedotcom.ui.commands.UpdateCustomObjectTestStepCommand.CustomObjectName">Account</propertyValue>
+  </parameterGeneratorProperties>
+  <generatedParameters>
+    <apiParam group="fields" modelBinding="sf:ui:binding:object?object=Account&amp;field=Industry" name="Industry" title="Industry"/>
+  </generatedParameters>
+</apiCall>
+```
+
+### ApexDeleteObject
+
+Deletes a record by ID. No `parameterGeneratorUri` required.
+
+```xml
+<apiCall apiId="com.provar.plugins.forcedotcom.core.testapis.ApexDeleteObject"
+         name="ApexDeleteObject" testItemId="1"
+         title="Delete Object: {AccountId}">
+  <arguments>
+    <argument id="apexConnectionName">
+      <value class="value" valueClass="string">Admin</value>
+    </argument>
+    <argument id="objectId">
+      <value class="variable">
+        <path element="AccountId"/>
+      </value>
+    </argument>
+  </arguments>
+</apiCall>
+```
+
+### ApexSoqlQuery
+
+Runs a SOQL query and stores results as a list variable. Always include `Id` and `Name` in the SELECT clause. Always specify `resultListName` and `resultScope`.
+
+```xml
+<apiCall apiId="com.provar.plugins.forcedotcom.core.testapis.ApexSoqlQuery"
+         name="ApexSoqlQuery" testItemId="1"
+         title="SOQL Query: SELECT Id, Name FROM Account=&gt;AccountRows">
+  <arguments>
+    <argument id="apexConnectionName">
+      <value class="value" valueClass="string">Admin</value>
+    </argument>
+    <argument id="soqlQuery">
+      <value class="value" valueClass="string">SELECT Id, Name FROM Account WHERE Name = 'Test Account'</value>
+    </argument>
+    <argument id="resultListName">
+      <value class="value" valueClass="string">AccountRows</value>
+    </argument>
+    <argument id="resultScope">
+      <value class="value" valueClass="string">Test</value>
+    </argument>
+  </arguments>
+</apiCall>
+```
+
+---
+
+## Control Flow
+
+### SetValues
+
+Sets one or more test variables. Use this for all test data instead of hardcoding values across multiple steps. Variable names must match `^[A-Za-z_][A-Za-z0-9_]*$`.
+
+> **`dataTable` binding is ignored by the CLI.** Always use `SetValues` for parameterized data when tests
+> run via `sf provar automation testrun` or Quality Hub.
+
+```xml
+<apiCall apiId="com.provar.plugins.bundled.apis.control.SetValues"
+         name="SetValues" testItemId="1"
+         title="Set Test Data Variables">
+  <arguments>
+    <argument id="values">
+      <value class="valueList" mutable="Mutable">
+        <namedValues mutable="Mutable">
+          <namedValue name="AccountName">
+            <value class="value" valueClass="string">Acme Corporation</value>
+          </namedValue>
+          <namedValue name="PhoneNumber">
+            <value class="value" valueClass="string">555-123-4567</value>
+          </namedValue>
+          <namedValue name="IsActive">
+            <value class="value" valueClass="boolean">true</value>
+          </namedValue>
+        </namedValues>
+      </value>
+    </argument>
+  </arguments>
+</apiCall>
+```
+
+### StepGroup
+
+Groups steps with a shared label. Substeps go in `<clause name="hidden">`.
+
+```xml
+<apiCall apiId="com.provar.plugins.bundled.apis.control.StepGroup"
+         name="StepGroup" testItemId="1"
+         title="Setup - Create Connection">
+  <arguments>
+    <argument id="description">
+      <value class="value" valueClass="string">Establish connection to Salesforce</value>
+    </argument>
+  </arguments>
+  <clauses>
+    <clause name="hidden" testItemId="2">
+      <steps>
+        <!-- Steps go here -->
+      </steps>
+    </clause>
+  </clauses>
+</apiCall>
+```
+
+### If
+
+```xml
+<apiCall apiId="com.provar.plugins.bundled.apis.If"
+         name="If" testItemId="1"
+         title="If: {IsActive}">
+  <arguments>
+    <argument id="condition">
+      <value class="value" valueClass="string">{IsActive} == true</value>
+    </argument>
+  </arguments>
+  <clauses>
+    <clause name="then" testItemId="2">
+      <steps>
+        <!-- Steps if condition is true -->
+      </steps>
+    </clause>
+    <clause name="else" testItemId="3">
+      <steps>
+        <!-- Steps if condition is false -->
+      </steps>
+    </clause>
+  </clauses>
+</apiCall>
+```
+
+### ForEach
+
+Iterates over a list variable. `list` must reference an existing variable. `valueName` must be unique within scope.
+
+```xml
+<apiCall apiId="com.provar.plugins.bundled.apis.control.ForEach"
+         name="ForEach" testItemId="1"
+         title="For Each: {AccountRows}=&gt;CurrentRow">
+  <arguments>
+    <argument id="list">
+      <value class="variable">
+        <path element="AccountRows"/>
+      </value>
+    </argument>
+    <argument id="fromItem">
+      <value class="value" valueClass="decimal">1</value>
+    </argument>
+    <argument id="valueName">
+      <value class="value" valueClass="string">CurrentRow</value>
+    </argument>
+    <argument id="continueOnFailure">
+      <value class="value" valueClass="boolean">false</value>
+    </argument>
+  </arguments>
+  <clauses>
+    <clause name="substeps" testItemId="2">
+      <steps>
+        <!-- Loop body -->
+      </steps>
+    </clause>
+  </clauses>
+</apiCall>
+```
+
+### TryCatchFinally
+
+Wraps steps with error handling. The `finally` clause always runs, making it the right place for cleanup steps (e.g., delete records created during the test).
+
+```xml
+<apiCall apiId="com.provar.plugins.bundled.apis.control.TryCatchFinally"
+         name="TryCatchFinally" testItemId="1"
+         title="Try/Catch/Finally">
+  <clauses>
+    <clause name="try" testItemId="2">
+      <steps>
+        <!-- Main test steps -->
+      </steps>
+    </clause>
+    <clause name="catch" testItemId="3">
+      <steps>
+        <!-- Steps to run on failure (optional) -->
+      </steps>
+    </clause>
+    <clause name="finally" testItemId="4">
+      <steps>
+        <!-- Cleanup: always runs, even on failure -->
+      </steps>
+    </clause>
+  </clauses>
+</apiCall>
+```
+
+### WaitFor
+
+Polls a condition at intervals until true or max iterations are reached.
+
+```xml
+<apiCall apiId="com.provar.plugins.bundled.apis.control.WaitFor"
+         name="WaitFor" testItemId="1"
+         title="Wait For: {IsComplete}">
+  <arguments>
+    <argument id="condition">
+      <value class="value" valueClass="string">{IsComplete} == true</value>
+    </argument>
+    <argument id="testAtStart">
+      <value class="value" valueClass="boolean">true</value>
+    </argument>
+    <argument id="maxIterations">
+      <value class="value" valueClass="decimal">10</value>
+    </argument>
+    <argument id="sleepSecs">
+      <value class="value" valueClass="decimal">2</value>
+    </argument>
+    <argument id="continueOnFailure">
+      <value class="value" valueClass="boolean">false</value>
+    </argument>
+  </arguments>
+  <clauses>
+    <clause name="substeps" testItemId="2">
+      <steps>
+        <!-- Steps to check the condition -->
+      </steps>
+    </clause>
+  </clauses>
+</apiCall>
+```
+
+> **Rule CONTROL-WAITFOR-002:** `maxIterations` is required — omitting it produces an infinite loop.
+
+### Sleep
+
+```xml
+<apiCall apiId="com.provar.plugins.bundled.apis.control.Sleep"
+         name="Sleep" testItemId="1"
+         title="Sleep for 5 seconds">
+  <arguments>
+    <argument id="sleepSecs">
+      <value class="value" valueClass="decimal">5</value>
+    </argument>
+  </arguments>
+</apiCall>
+```
+
+### CallTest
+
+Calls another test case as a step (callable tests have `visibility="Internal"`). Use this to share setup logic across test cases.
+
+```xml
+<apiCall apiId="com.provar.plugins.bundled.apis.control.CallTest"
+         name="CallTest" testItemId="1"
+         title="Call: Create Lead API">
+  <arguments>
+    <argument id="testCase">
+      <value class="value" valueClass="string">Callables/Create Lead API</value>
+    </argument>
+    <argument id="LastName">
+      <value class="value" valueClass="string">Smith</value>
+    </argument>
+    <argument id="Company">
+      <value class="value" valueClass="string">Acme</value>
+    </argument>
+  </arguments>
+</apiCall>
+```
+
+---
+
+## Assertions
+
+### AssertValues
+
+Variable-to-variable or variable-to-literal comparison. For UI field assertions use `UiAssert` instead.
+
+```xml
+<apiCall apiId="com.provar.plugins.bundled.apis.AssertValues"
+         name="AssertValues" testItemId="1"
+         title="Assert: {Expected} EqualTo {Actual}">
+  <arguments>
+    <argument id="expectedValue">
+      <value class="variable">
+        <path element="ExpectedValue"/>
+      </value>
+    </argument>
+    <argument id="comparisonType">
+      <value class="value" valueClass="string">EqualTo</value>
+    </argument>
+    <argument id="actualValue">
+      <value class="variable">
+        <path element="ActualValue"/>
+      </value>
+    </argument>
+    <argument id="caseSensitive">
+      <value class="value" valueClass="boolean">false</value>
+    </argument>
+    <argument id="numeric">
+      <value class="value" valueClass="boolean">false</value>
+    </argument>
+    <argument id="failureMessage">
+      <value class="value" valueClass="string">Values do not match</value>
+    </argument>
+  </arguments>
+</apiCall>
+```
+
+---
+
+## BDD Steps
+
+`Given`, `When`, `Then`, `And`, `But` all share the same structure: a `description` argument and a `hidden` clause for substeps. Use them to add a BDD narrative layer over standard steps.
+
+```xml
+<apiCall apiId="com.provar.plugins.bundled.apis.bdd.Given"
+         name="Given" testItemId="1"
+         title="Given: The user is logged in to Salesforce">
+  <arguments>
+    <argument id="description">
+      <value class="value" valueClass="string">The user is logged in to Salesforce</value>
+    </argument>
+  </arguments>
+  <clauses>
+    <clause name="hidden" testItemId="2">
+      <steps>
+        <!-- ApexConnect or UiConnect steps go here -->
+      </steps>
+    </clause>
+  </clauses>
+</apiCall>
+
+<!-- And / But follow the same structure -->
+<apiCall apiId="com.provar.plugins.bundled.apis.bdd.And"
+         name="And" testItemId="5"
+         title="And: The opportunity stage is set to Closed Won">
+  <arguments>
+    <argument id="description">
+      <value class="value" valueClass="string">The opportunity stage is set to Closed Won</value>
+    </argument>
+  </arguments>
+  <clauses>
+    <clause name="hidden" testItemId="6">
+      <steps>
+        <!-- Steps -->
+      </steps>
+    </clause>
+  </clauses>
+</apiCall>
+```
+
+---
+
+## Database Steps
+
+### DbConnect
+
+```xml
+<apiCall apiId="com.provar.plugins.bundled.apis.db.DbConnect"
+         name="DbConnect" testItemId="1"
+         title="DB Connect: DbConnection">
+  <arguments>
+    <argument id="connectionName">
+      <value class="value" valueClass="string">MyDatabase</value>
+    </argument>
+    <argument id="connectionId">
+      <value class="value" valueClass="string">database-connection-id</value>
+    </argument>
+    <argument id="autoCommit">
+      <value class="value" valueClass="boolean">true</value>
+    </argument>
+    <argument id="resultName">
+      <value class="value" valueClass="string">DbConnection</value>
+    </argument>
+    <argument id="resultScope">
+      <value class="value" valueClass="string">Test</value>
+    </argument>
+  </arguments>
+</apiCall>
+```
+
+### SqlQuery
+
+```xml
+<apiCall apiId="com.provar.plugins.bundled.apis.db.SqlQuery"
+         name="SqlQuery" testItemId="1"
+         title="SQL Query: DbConnection=&gt;DbResults">
+  <arguments>
+    <argument id="dbConnectionName">
+      <value class="value" valueClass="string">DbConnection</value>
+    </argument>
+    <argument id="query">
+      <value class="value" valueClass="string">SELECT * FROM Users WHERE Status = 'Active'</value>
+    </argument>
+    <argument id="resultName">
+      <value class="value" valueClass="string">DbResults</value>
+    </argument>
+    <argument id="resultScope">
+      <value class="value" valueClass="string">Test</value>
+    </argument>
+  </arguments>
+</apiCall>
+```
+
+---
+
+## Web Service Steps
+
+### WebConnect
+
+```xml
+<apiCall apiId="com.provar.plugins.bundled.apis.restservice.WebConnect"
+         name="WebConnect" testItemId="1"
+         title="Web Connect: WebServiceConnection">
+  <arguments>
+    <argument id="connectionName">
+      <value class="value" valueClass="string">MyWebService</value>
+    </argument>
+    <argument id="connectionId">
+      <value class="value" valueClass="string">web-service-connection-id</value>
+    </argument>
+    <argument id="resultName">
+      <value class="value" valueClass="string">WebServiceConnection</value>
+    </argument>
+    <argument id="resultScope">
+      <value class="value" valueClass="string">Test</value>
+    </argument>
+  </arguments>
+</apiCall>
+```
+
+### RestRequest
+
+```xml
+<apiCall apiId="com.provar.plugins.bundled.apis.restservice.RestRequest"
+         name="RestRequest" testItemId="1"
+         title="Web Request (REST): GET /api/users=&gt;RestResponse">
+  <arguments>
+    <argument id="connectionName">
+      <value class="value" valueClass="string">WebServiceConnection</value>
+    </argument>
+    <argument id="targetValue">
+      <value class="value" valueClass="string">GET</value>
+    </argument>
+    <argument id="resultName">
+      <value class="value" valueClass="string">RestResponse</value>
+    </argument>
+    <argument id="resultScope">
+      <value class="value" valueClass="string">Test</value>
+    </argument>
+    <argument id="statusResultName">
+      <value class="value" valueClass="string">RestStatus</value>
+    </argument>
+    <argument id="restResourceUrl">
+      <value class="value" valueClass="string">/api/users</value>
+    </argument>
+  </arguments>
+</apiCall>
+```
+
+---
+
+## Value Types Reference
+
+```xml
+<!-- String literal -->
+<value class="value" valueClass="string">Text content</value>
+
+<!-- Boolean -->
+<value class="value" valueClass="boolean">true</value>
+
+<!-- Number -->
+<value class="value" valueClass="decimal">123.45</value>
+
+<!-- GUID / record ID — required for connectionId on ApexConnect -->
+<value class="value" valueClass="id">74c34c63-ad34-43d9-bb12-cd783bd9bcdd</value>
+
+<!-- Variable reference -->
+<value class="variable">
+  <path element="VariableName"/>
+</value>
+
+<!-- Nested object field access -->
+<value class="variable">
+  <path element="ObjectName"/>
+  <path element="FieldName"/>
+</value>
+
+<!-- String concatenation (compound) -->
+<value class="compound">
+  <parts>
+    <value class="value" valueClass="string">Prefix </value>
+    <value class="variable">
+      <path element="DynamicPart"/>
+    </value>
+    <value class="value" valueClass="string"> suffix</value>
+  </parts>
+</value>
+
+<!-- UI wait (use on beforeWait / afterWait) -->
+<value class="uiWait" uri="default"/>
+
+<!-- UI wait with custom timeout (use on autoRetry) -->
+<value class="uiWait" uri="ui:wait:autoRetry:timeout=10"/>
+```
+
+---
+
+## Callable Test Structure
+
+A callable test (used by `CallTest`) declares its interface via `<params>`, `<outputParams>`, `<args>`, and `<outputArgs>` elements. Set `visibility="Internal"` on the `<testCase>` root.
+
+```xml
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<testCase guid="..." visibility="Internal">
+  <summary/>
+  <steps>
+    <!-- Steps that use input params as variables -->
+  </steps>
+  <params>
+    <param name="LastName" title="Last Name" passwordVariableAllowed="true">
+      <summary/>
+    </param>
+  </params>
+  <outputParams>
+    <param name="RecordId" title="Record Id" passwordVariableAllowed="true">
+      <summary/>
+      <sourceValue class="variable">
+        <path element="RecordId"/>
+      </sourceValue>
+    </param>
+  </outputParams>
+  <args>
+    <argument id="LastName"/>
+  </args>
+  <outputArgs>
+    <outputArgument id="RecordId">
+      <name class="value" valueClass="string">RecordId</name>
+    </outputArgument>
+  </outputArgs>
+</testCase>
+```
+
+---
+
+## Validation Checklist
+
+- [ ] **API IDs** — exact match from the reference table above (no variations, no `<UI4SF:*>` elements)
+- [ ] **Connections** — first step is `ApexConnect` or `UiConnect`; `resultName` is referenced consistently by all subsequent steps
+- [ ] **`connectionId`** — uses `valueClass="id"` (GUID), not `valueClass="string"`
+- [ ] **UI nesting** — `UiDoAction` and `UiAssert` are always inside `<clause name="substeps">` of a `UiWithScreen`
+- [ ] **First UiWithScreen** — `navigate` is `Always` or `IfNecessary`, never `Dont`
+- [ ] **UiWithScreen on Edit/View with `navigate=Always`** — includes `sfUiTargetObjectId` referencing a variable
+- [ ] **UiAssert required arguments** — `columnAssertions`, `pageAssertions`, `resultScope`, `captureAfter`, `beforeWait`, `autoRetry` all present (may be empty)
+- [ ] **UiAssert no generatedParameters** — do not add a `<generatedParameters>` block to `UiAssert`
+- [ ] **UiConnect arguments** — does NOT include `autoCleanup`, `quickUiLogin`, `closeAllPrimaryTabs`, `alreadyOpenBehaviour`, `lightningMode`, `uiApplicationName`, `cleanupConnectionName`
+- [ ] **SOQL** — queries include `SELECT` and `FROM`; include `Id` and `Name`; use `resultListName`
+- [ ] **CRUD result capture** — `ApexCreateObject` has `resultIdName`; `ApexReadObject` has `objectId` (variable)
+- [ ] **CRUD generator metadata** — `ApexCreateObject`, `ApexReadObject`, `ApexUpdateObject` include `parameterGeneratorUri`, `parameterGeneratorProperties`, and `generatedParameters`
+- [ ] **Variable definition** — variables used as `<value class="variable">` are defined by a prior step in scope
+- [ ] **Control flow** — `If` has `condition`; `ForEach` has `list` and `valueName`; `WaitFor` has `maxIterations`
+- [ ] **SetValues structure** — `values` argument contains `<value class="valueList">` wrapping `<namedValues>` wrapping `<namedValue>` elements
+- [ ] **Data types** — booleans are string `"true"`/`"false"` inside `valueClass="boolean"`; numbers use `valueClass="decimal"`
+- [ ] **Cleanup** — either `autoCleanup="true"` on the connection, or explicit `ApexDeleteObject` / `TryCatchFinally` finally block
+- [ ] **No hallucinated arguments** — see the Common AI Hallucinations table at the top of this doc

From 6948dcb49bc5f8edebd0786d575bfffe1696031f Mon Sep 17 00:00:00 2001
From: Michael Dailey <michael.dailey@provartesting.com>
Date: Wed, 22 Apr 2026 15:04:13 -0500
Subject: [PATCH 02/12] PDX-0: feat(mcp): add migration and AI loop MCP prompts
 for Provar test generation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Req: Phase 2 corpus feature — orchestrated MCP prompts that ground AI agents in corpus examples before generating or fixing Provar XML test cases
Fix: Register 7 prompts via MCP protocol: provar.migrate.crt/selenium/playwright and provar.loop.generate/fix/review/coverage

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/mcp/prompts/index.ts            |  29 +++
 src/mcp/prompts/loopPrompts.ts      | 384 ++++++++++++++++++++++++++++
 src/mcp/prompts/migrationPrompts.ts | 249 ++++++++++++++++++
 3 files changed, 662 insertions(+)
 create mode 100644 src/mcp/prompts/index.ts
 create mode 100644 src/mcp/prompts/loopPrompts.ts
 create mode 100644 src/mcp/prompts/migrationPrompts.ts

diff --git a/src/mcp/prompts/index.ts b/src/mcp/prompts/index.ts
new file mode 100644
index 00000000..21bdd8e0
--- /dev/null
+++ b/src/mcp/prompts/index.ts
@@ -0,0 +1,29 @@
+/*
+ * Copyright (c) 2024 Provar Limited.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.md file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import {
+  registerCrtMigrationPrompt,
+  registerSeleniumMigrationPrompt,
+  registerPlaywrightMigrationPrompt,
+} from './migrationPrompts.js';
+import {
+  registerLoopGeneratePrompt,
+  registerLoopFixPrompt,
+  registerLoopReviewPrompt,
+  registerLoopCoveragePrompt,
+} from './loopPrompts.js';
+
+export function registerAllPrompts(server: McpServer): void {
+  registerCrtMigrationPrompt(server);
+  registerSeleniumMigrationPrompt(server);
+  registerPlaywrightMigrationPrompt(server);
+  registerLoopGeneratePrompt(server);
+  registerLoopFixPrompt(server);
+  registerLoopReviewPrompt(server);
+  registerLoopCoveragePrompt(server);
+}
diff --git a/src/mcp/prompts/loopPrompts.ts b/src/mcp/prompts/loopPrompts.ts
new file mode 100644
index 00000000..b2bdd4c3
--- /dev/null
+++ b/src/mcp/prompts/loopPrompts.ts
@@ -0,0 +1,384 @@
+/*
+ * Copyright (c) 2024 Provar Limited.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.md file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+// ── Shared helpers ────────────────────────────────────────────────────────────
+
+function projectHint(projectPath: string | undefined): string {
+  return projectPath
+    ? `The Provar project root is: ${projectPath}`
+    : 'Ask the user for the Provar project root path if it is needed for file operations.';
+}
+
+// ── Prompt: provar.loop.generate ─────────────────────────────────────────────
+
+export function registerLoopGeneratePrompt(server: McpServer): void {
+  server.prompt(
+    'provar.loop.generate',
+    'Generate a Provar XML test case from a user story or acceptance criteria. Retrieves corpus examples for grounding, generates the test, writes it to the project, then validates it with provar.testcase.validate.',
+    {
+      story: z
+        .string()
+        .describe(
+          'The user story or acceptance criteria to test. Paste the full story text, or a numbered list of acceptance criteria. Include the Salesforce object name and the action being tested (e.g. "As a sales rep, I want to close an opportunity so that revenue is recorded").'
+        ),
+      projectPath: z
+        .string()
+        .optional()
+        .describe(
+          'Absolute path to the Provar project root. Used to locate the tests/ directory when writing the output file.'
+        ),
+      testName: z
+        .string()
+        .optional()
+        .describe(
+          'Optional name for the output test case file (without extension). Inferred from the story if omitted.'
+        ),
+      objectName: z
+        .string()
+        .optional()
+        .describe(
+          'Primary Salesforce object under test (e.g. "Opportunity", "Lead"). Helps scope the corpus query if present.'
+        ),
+    },
+    ({ story, projectPath, testName, objectName }) => ({
+      messages: [
+        {
+          role: 'user' as const,
+          content: {
+            type: 'text' as const,
+            text: `You are a Provar test automation expert. Generate a Provar XML test case from the user story below.
+
+## Workflow
+
+Follow these steps in order:
+
+1. **Extract keywords** — identify the Salesforce object, the action (create/update/close/delete/view), and key
+   scenario details from the story. Use these as the query for step 2.
+
+2. **Get corpus examples** — call \`provar.qualityhub.examples.retrieve\` with the keywords you extracted
+   (e.g. "close opportunity" or "create lead"). Use the returned XML examples as the sole reference for
+   Provar step structure and argument patterns. Do not invent XML structure from prior knowledge.
+
+3. **Map acceptance criteria to steps** — for each acceptance criterion, identify the corresponding Provar
+   step type: field fills → UiDoAction (set), button clicks → UiDoAction (action), field checks →
+   UiAssert, API data setup → ApexCreateObject, API verification → ApexReadObject.
+
+4. **Generate the test case** — produce a valid Provar XML test case that tests the story's acceptance
+   criteria. Base the structure entirely on the corpus examples. Follow these rules:
+   - All UI steps must be nested inside UiWithScreen blocks
+   - The first UiWithScreen must use navigate="Always"
+   - UiAssert requires columnAssertions, pageAssertions, resultScope, captureAfter, beforeWait, autoRetry
+   - Use ApexConnect for the connection step (first step in the test)
+   - Wrap test body in TryCatchFinally if cleanup is needed (ApexDeleteObject in the finally clause)
+
+5. **Write the file** — save the XML to the tests/ directory in the Provar project.
+   ${projectHint(projectPath)}
+   ${testName ? `Target file name: ${testName}.testcase` : 'Infer the file name from the story (snake_case).'}
+
+6. **Validate** — call \`provar.testcase.validate\` on the saved file. If it reports errors, fix them
+   and re-validate until the file passes clean.
+
+7. **Report** — summarise:
+   - Which acceptance criteria were covered and how
+   - Any criteria that could not be automated (add \`<!-- TODO: manual verification — <criterion> -->\` in the XML)
+   - Any validation warnings
+
+## User Story
+
+${story}
+
+${objectName ? `Primary object: ${objectName}` : ''}
+
+Begin with step 1: extract keywords, then call provar.qualityhub.examples.retrieve.`,
+          },
+        },
+      ],
+    })
+  );
+}
+
+// ── Prompt: provar.loop.fix ───────────────────────────────────────────────────
+
+export function registerLoopFixPrompt(server: McpServer): void {
+  server.prompt(
+    'provar.loop.fix',
+    'Fix a failing Provar test case using the output from provar.testrun.rca. Reads the current XML, retrieves corpus examples for the failing step type, applies targeted fixes, then re-validates.',
+    {
+      testcasePath: z
+        .string()
+        .describe(
+          'Absolute path to the failing .testcase XML file. The file must be readable and within the --allowed-paths configured for this MCP server.'
+        ),
+      rcaOutput: z
+        .string()
+        .describe(
+          'The RCA report text from provar.testrun.rca, or a raw failure message from a test run. Include the full error text — step name, error type, and message. The more detail, the better the fix.'
+        ),
+      projectPath: z
+        .string()
+        .optional()
+        .describe('Absolute path to the Provar project root. Used to locate adjacent test files if needed.'),
+    },
+    ({ testcasePath, rcaOutput, projectPath }) => ({
+      messages: [
+        {
+          role: 'user' as const,
+          content: {
+            type: 'text' as const,
+            text: `You are a Provar test automation expert. Fix the failing test case at the path below.
+
+## Failing test case
+
+Path: ${testcasePath}
+
+## RCA output
+
+\`\`\`
+${rcaOutput}
+\`\`\`
+
+${projectPath ? `Provar project root: ${projectPath}` : ''}
+
+## Workflow
+
+Follow these steps in order:
+
+1. **Read the failing test case** — read the XML file at the path above using your file reading tools.
+
+2. **Parse the failure** — from the RCA output, identify:
+   - Which step is failing (step name, testItemId, or title)
+   - The failure category (e.g. element not found, assertion mismatch, connection error, XML structure error)
+   - The specific error message
+
+3. **Get corpus examples** — call \`provar.qualityhub.examples.retrieve\` with keywords describing the
+   failing step's scenario (e.g. "close opportunity UiDoAction" or "assert field value UiAssert").
+   Use the returned examples to verify the correct structure for the failing step type.
+
+4. **Diagnose the root cause** — compare the failing step's XML against the corpus examples. Common issues:
+   - Wrong interaction URI (action vs set vs file)
+   - Missing required UiAssert arguments (columnAssertions, pageAssertions, resultScope, captureAfter, beforeWait, autoRetry)
+   - UiDoAction (set) missing the value argument
+   - UiWithScreen navigate="Dont" on the first screen
+   - navigate="Always" on Edit/View without sfUiTargetObjectId
+   - Incorrect locator URI format
+   - connectionId using valueClass="string" instead of valueClass="id"
+
+5. **Apply the fix** — rewrite only the failing step(s). Preserve all other steps unchanged. Write the
+   updated XML back to the same file path.
+
+6. **Validate** — call \`provar.testcase.validate\` on the updated file. If new errors appear, fix them
+   and re-validate until the file passes clean.
+
+7. **Report** — summarise:
+   - The root cause of the failure
+   - Exactly what was changed (step name, argument changed, before/after values)
+   - Any remaining warnings from validation
+
+Begin with step 1: read the file at: ${testcasePath}`,
+          },
+        },
+      ],
+    })
+  );
+}
+
+// ── Prompt: provar.loop.review ────────────────────────────────────────────────
+
+export function registerLoopReviewPrompt(server: McpServer): void {
+  server.prompt(
+    'provar.loop.review',
+    'Review a Provar test case for quality before committing. Runs structural validation, checks against corpus best practices, and reports quality gaps: missing assertions, hardcoded data, missing cleanup, and unmapped steps.',
+    {
+      testcasePath: z
+        .string()
+        .describe(
+          'Absolute path to the .testcase XML file to review. Must be within the --allowed-paths configured for this MCP server.'
+        ),
+      projectPath: z.string().optional().describe('Absolute path to the Provar project root.'),
+    },
+    ({ testcasePath, projectPath }) => ({
+      messages: [
+        {
+          role: 'user' as const,
+          content: {
+            type: 'text' as const,
+            text: `You are a Provar test automation expert. Review the test case at the path below for quality and completeness.
+
+## Test case to review
+
+Path: ${testcasePath}
+${projectPath ? `Provar project root: ${projectPath}` : ''}
+
+## Workflow
+
+Follow these steps in order:
+
+1. **Validate** — call \`provar.testcase.validate\` on the file. Note all errors and warnings. Do not stop
+   here even if the file is valid — continue the review.
+
+2. **Read the file** — read the XML to understand the test structure: what object is being tested, what
+   actions are performed, and what is being asserted.
+
+3. **Get corpus examples** — call \`provar.qualityhub.examples.retrieve\` with keywords describing the
+   test scenario (e.g. "create opportunity", "close opportunity"). Use the returned examples as a
+   quality baseline.
+
+4. **Review for quality gaps** — check for each of the following, noting pass or fail:
+
+   **Coverage**
+   - [ ] Does the test assert the outcome of each action? (e.g. after clicking Save, is there a UiAssert?)
+   - [ ] Are all required fields verified, not just the ones that were set?
+   - [ ] Is there at least one UiAssert or ApexReadObject in the test?
+
+   **Data quality**
+   - [ ] Are test data values parameterised via SetValues rather than hardcoded in multiple steps?
+   - [ ] Are dynamic values (dates, IDs) referenced via variables rather than hardcoded strings?
+
+   **Cleanup**
+   - [ ] Is cleanup handled? Either autoCleanup=true on the connection, or ApexDeleteObject steps, or
+         a TryCatchFinally with cleanup in the finally clause?
+
+   **Structure**
+   - [ ] Does the first UiWithScreen use navigate="Always" or "IfNecessary"?
+   - [ ] Do Edit/View UiWithScreen steps with navigate="Always" include sfUiTargetObjectId?
+   - [ ] Are all UiDoAction and UiAssert steps inside UiWithScreen substeps clauses?
+
+   **Unmapped steps**
+   - [ ] Are there any \`<!-- TODO: -->\` comments indicating steps that couldn't be automated?
+         Flag these for manual review.
+
+5. **Report** — produce a structured review with three sections:
+
+   ### Passes
+   List what the test does well.
+
+   ### Issues
+   For each gap found, state:
+   - What is missing or wrong
+   - Why it matters (e.g. "assertion missing after Save means the test won't catch a silent failure")
+   - A concrete fix (reference the corpus example if relevant)
+
+   ### Suggested improvements
+   Any non-blocking suggestions (e.g. parameterising a hardcoded value that appears more than once).
+
+Begin with step 1: call provar.testcase.validate on the file at: ${testcasePath}`,
+          },
+        },
+      ],
+    })
+  );
+}
+
+// ── Prompt: provar.loop.coverage ─────────────────────────────────────────────
+
+export function registerLoopCoveragePrompt(server: McpServer): void {
+  server.prompt(
+    'provar.loop.coverage',
+    'Analyse test coverage for a Salesforce object. Scans the Provar project test files to identify which CRUD operations, field validations, and UI workflows are covered, then reports gaps with suggested test outlines.',
+    {
+      objectName: z
+        .string()
+        .describe(
+          'The Salesforce API object name to analyse (e.g. "Opportunity", "Lead", "Contact", "Account"). Used to scan test cases and query the corpus for expected test patterns.'
+        ),
+      projectPath: z
+        .string()
+        .describe(
+          'Absolute path to the Provar project root. The tests/ subdirectory will be scanned for .testcase files.'
+        ),
+      targetOrg: z
+        .string()
+        .optional()
+        .describe(
+          'SF org alias or username. If provided, also queries provar.qualityhub.testcase.retrieve to include Quality Hub tests in the coverage analysis.'
+        ),
+    },
+    ({ objectName, projectPath, targetOrg }) => ({
+      messages: [
+        {
+          role: 'user' as const,
+          content: {
+            type: 'text' as const,
+            text: `You are a Provar test automation expert. Analyse test coverage for the Salesforce object "${objectName}".
+
+## Provar project
+
+Root: ${projectPath}
+Object to analyse: ${objectName}
+${targetOrg ? `Quality Hub org: ${targetOrg}` : ''}
+
+## Workflow
+
+Follow these steps in order:
+
+1. **Scan local test files** — list all .testcase files under ${projectPath}/tests/. For each file that
+   references "${objectName}" (search for the string in the file content), read it and extract:
+   - The test scenario (from the file name or meta comment)
+   - Which operations are covered: API Create, API Read, API Update, API Delete, UI New, UI View,
+     UI Edit, UI Delete, UI assertions on fields
+   - Which fields are set or asserted
+
+${
+  targetOrg
+    ? `2. **Query Quality Hub** — call \`provar.qualityhub.testcase.retrieve\` with target_org="${targetOrg}"
+   to retrieve test cases linked to the "${objectName}" object from Quality Hub. Add these to the
+   coverage inventory.
+
+3. **Get corpus examples** — call \`provar.qualityhub.examples.retrieve\` with "${objectName.toLowerCase()}"
+   as the query to understand what test patterns exist in the corpus for this object.`
+    : `2. **Get corpus examples** — call \`provar.qualityhub.examples.retrieve\` with "${objectName.toLowerCase()}"
+   as the query to understand what test patterns exist in the corpus for this object.`
+}
+
+${targetOrg ? '4' : '3'}. **Build the coverage matrix** — define the standard test scenarios for "${objectName}":
+
+   **API (Apex) operations**
+   - Create: ApexCreateObject with required fields
+   - Create: ApexCreateObject with optional/edge-case fields
+   - Read: ApexReadObject — verify created record
+   - Update: ApexUpdateObject — modify field values
+   - Delete: ApexDeleteObject — confirm record removed
+   - SOQL: ApexSoqlQuery — query by key fields
+
+   **UI operations**
+   - New: navigate to New screen, fill required fields, save → assert record created
+   - View: navigate to View screen → assert field values
+   - Edit: navigate to Edit screen, modify fields, save → assert changes persisted
+   - Delete: delete via UI → confirm record no longer visible
+   - Related lists: any relationships (e.g. Contacts on Account) that have UI tests
+
+   **Validation rules and required fields**
+   - Negative tests: attempt to save with missing required fields → assert error message shown
+   - Validation rule triggers: if known validation rules exist, is there a test for each?
+
+${targetOrg ? '5' : '4'}. **Report coverage gaps** — produce a report with three sections:
+
+   ### Covered
+   List each scenario that has at least one test, with the test file name.
+
+   ### Gaps
+   For each missing scenario, state:
+   - What is not covered
+   - Why it matters (e.g. "No negative test for required fields means validation rule regressions won't be caught")
+   - A brief test outline (inputs, expected outcome, which step types to use)
+
+   ### Suggested next tests
+   Rank the top 3-5 gaps by risk. For each, provide:
+   - A suggested test case name
+   - The key steps (using correct Provar step type names from the reference)
+   - Estimated effort (XS / S / M)
+
+Begin with step 1: list the .testcase files in ${projectPath}/tests/ and search for "${objectName}".`,
+          },
+        },
+      ],
+    })
+  );
+}
diff --git a/src/mcp/prompts/migrationPrompts.ts b/src/mcp/prompts/migrationPrompts.ts
new file mode 100644
index 00000000..d0fa6f28
--- /dev/null
+++ b/src/mcp/prompts/migrationPrompts.ts
@@ -0,0 +1,249 @@
+/*
+ * Copyright (c) 2024 Provar Limited.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.md file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+// Source-framework context injected into each migration prompt.
+// Lightweight: just enough to interpret the source. Format knowledge lives
+// in the corpus (provar.qualityhub.examples.retrieve) and the validator
+// (provar.testcase.validate) — not hardcoded here.
+
+const CRT_CONTEXT = `
+CRT (Copado Robotic Testing) is a keyword-driven framework built on Robot Framework.
+Tests are authored in QEditor using QWords:
+- ClickText <label>         → click an element by visible label
+- TypeText <field> <value>  → type a value into a field
+- VerifyText <text>         → assert text is present on the page
+- SelectDropdown <field> <val> → choose a picklist option
+- OpenBrowser <url>         → open a browser session (maps to Salesforce login)
+
+Robot Framework sections: *** Keywords *** define reusable blocks; *** Test Cases *** are the test entries.
+Suite Setup/Teardown → login at the start and cleanup at the end.
+`.trim();
+
+const SELENIUM_CONTEXT = `
+Selenium WebDriver test patterns (Java/Python/JavaScript):
+- driver.get(url) / navigate().to() → navigate to a URL (maps to Salesforce login)
+- findElement(By.linkText/name).click() → click by visible label
+- findElement(...).sendKeys(value) → type into a field
+- Select.selectByVisibleText(val) → select a picklist option
+- findElement(...).getText() + assertion → verify a field value
+- WebDriverWait / ExpectedConditions → wait for element visibility
+- @Before / setUp() → test setup including login
+- @After / tearDown() → cleanup
+`.trim();
+
+const PLAYWRIGHT_CONTEXT = `
+Playwright test patterns (TypeScript/JavaScript):
+- page.goto(url) / login fixture → navigate to Salesforce (maps to login)
+- getByLabel(label).click() → click by visible label
+- getByRole('button', {name}).click() → click by button name
+- getByLabel(label).fill(value) → fill a field by label
+- locator(selector).fill(value) → fill by XPath/CSS selector
+- locator.selectOption(value) → choose a picklist option
+- expect(locator).toHaveValue(val) → assert a field value
+- expect(locator).toBeVisible() → assert element is visible
+- expect(page).toContainText(text) → assert text on page
+- page.waitForLoadState() / waitForSelector() → wait conditions
+- beforeEach → test setup including login
+`.trim();
+
+// ── Shared orchestration instructions ────────────────────────────────────────
+
+function migrationOrchestration(projectPath: string | undefined): string {
+  const projectHint = projectPath
+    ? `The target Provar project is at: ${projectPath}`
+    : 'Ask the user for the Provar project path if needed.';
+
+  return `
+## Migration workflow
+
+Follow these steps in order:
+
+1. **Get corpus examples** — call \`provar.qualityhub.examples.retrieve\` with keywords that
+   describe the source test's main scenario (e.g. "create opportunity", "close case", "convert lead").
+   Use the returned examples as few-shot grounding for the Provar XML format and step patterns.
+
+2. **Generate the test case** — produce a valid Provar XML test case that faithfully captures
+   the intent of the source test. Base the structure entirely on the corpus examples, not on
+   prior knowledge of Provar XML. Omit Salesforce login/navigation setup — Provar handles
+   that via Connection Manager.
+
+3. **Write the file** — save the generated XML to the appropriate \`tests/\` subdirectory
+   inside the Provar project. ${projectHint}
+
+4. **Validate** — call \`provar.testcase.validate\` on the saved file. If it reports errors,
+   fix them and re-validate until the file passes clean.
+
+5. **Report** — summarise what was migrated, any steps that could not be mapped (add them
+   as \`<!-- TODO: manual step -->\` comments in the XML), and any validation warnings.
+`.trim();
+}
+
+// ── Prompt: provar.migrate.crt ────────────────────────────────────────────────
+
+export function registerCrtMigrationPrompt(server: McpServer): void {
+  server.prompt(
+    'provar.migrate.crt',
+    'Convert a Copado Robotic Testing (CRT) test — either a QWord step sequence or a Robot Framework .robot file — into a Provar XML test case. Retrieves corpus examples for grounding, generates the test case, then validates it with provar.testcase.validate.',
+    {
+      source: z
+        .string()
+        .describe(
+          'The CRT test content to migrate. Accepts either: (1) a numbered QWord step sequence (e.g. "Step 1: ClickText Accounts"), or (2) a Robot Framework .robot file with *** Settings ***, *** Keywords ***, and *** Test Cases *** sections.'
+        ),
+      projectPath: z
+        .string()
+        .optional()
+        .describe(
+          'Absolute path to the Provar project root. Used to locate the tests/ directory when writing the output file.'
+        ),
+      testName: z
+        .string()
+        .optional()
+        .describe('Optional name for the output Provar test case. Inferred from the source if omitted.'),
+    },
+    ({ source, projectPath, testName }) => ({
+      messages: [
+        {
+          role: 'user' as const,
+          content: {
+            type: 'text' as const,
+            text: `You are a Provar test migration expert. Migrate the following CRT test to Provar.
+
+## Source format — CRT
+
+${CRT_CONTEXT}
+
+${migrationOrchestration(projectPath)}
+
+## Source CRT Test
+
+\`\`\`
+${source}
+\`\`\`
+
+${testName ? `Target test case name: ${testName}` : 'Infer the test case name from the source content.'}
+
+Begin with step 1: call provar.qualityhub.examples.retrieve.`,
+          },
+        },
+      ],
+    })
+  );
+}
+
+// ── Prompt: provar.migrate.selenium ──────────────────────────────────────────
+
+export function registerSeleniumMigrationPrompt(server: McpServer): void {
+  server.prompt(
+    'provar.migrate.selenium',
+    'Convert a Selenium WebDriver test (Java, Python, or JavaScript) that tests a Salesforce org into a Provar XML test case. Retrieves corpus examples for grounding, generates the test case, then validates it with provar.testcase.validate.',
+    {
+      source: z
+        .string()
+        .describe(
+          'The Selenium test file content to migrate. Accepts Java (JUnit/TestNG), Python (unittest/pytest), or JavaScript (Jest/Mocha) with selenium-webdriver. Include the full file or the relevant test method(s).'
+        ),
+      projectPath: z
+        .string()
+        .optional()
+        .describe(
+          'Absolute path to the Provar project root. Used to locate the tests/ directory when writing the output file.'
+        ),
+      testName: z
+        .string()
+        .optional()
+        .describe(
+          'Optional name for the output Provar test case. Inferred from the source class/method name if omitted.'
+        ),
+    },
+    ({ source, projectPath, testName }) => ({
+      messages: [
+        {
+          role: 'user' as const,
+          content: {
+            type: 'text' as const,
+            text: `You are a Provar test migration expert. Migrate the following Selenium WebDriver test to Provar.
+
+## Source format — Selenium WebDriver
+
+${SELENIUM_CONTEXT}
+
+${migrationOrchestration(projectPath)}
+
+## Source Selenium Test
+
+\`\`\`
+${source}
+\`\`\`
+
+${testName ? `Target test case name: ${testName}` : 'Infer the test case name from the class and method name.'}
+
+Begin with step 1: call provar.qualityhub.examples.retrieve.`,
+          },
+        },
+      ],
+    })
+  );
+}
+
+// ── Prompt: provar.migrate.playwright ────────────────────────────────────────
+
+export function registerPlaywrightMigrationPrompt(server: McpServer): void {
+  server.prompt(
+    'provar.migrate.playwright',
+    'Convert a Playwright test (TypeScript or JavaScript) that tests a Salesforce org into a Provar XML test case. Retrieves corpus examples for grounding, generates the test case, then validates it with provar.testcase.validate.',
+    {
+      source: z
+        .string()
+        .describe(
+          'The Playwright test file content to migrate. Accepts TypeScript or JavaScript using @playwright/test or the playwright library. Include the full file or the relevant test block(s).'
+        ),
+      projectPath: z
+        .string()
+        .optional()
+        .describe(
+          'Absolute path to the Provar project root. Used to locate the tests/ directory when writing the output file.'
+        ),
+      testName: z
+        .string()
+        .optional()
+        .describe(
+          'Optional name for the output Provar test case. Inferred from the test() block description if omitted.'
+        ),
+    },
+    ({ source, projectPath, testName }) => ({
+      messages: [
+        {
+          role: 'user' as const,
+          content: {
+            type: 'text' as const,
+            text: `You are a Provar test migration expert. Migrate the following Playwright test to Provar.
+
+## Source format — Playwright
+
+${PLAYWRIGHT_CONTEXT}
+
+${migrationOrchestration(projectPath)}
+
+## Source Playwright Test
+
+\`\`\`
+${source}
+\`\`\`
+
+${testName ? `Target test case name: ${testName}` : 'Infer the test case name from the test() block description.'}
+
+Begin with step 1: call provar.qualityhub.examples.retrieve.`,
+          },
+        },
+      ],
+    })
+  );
+}

From d1afbcd960bf7eb4639e7d7e8eb858c36e2dd173 Mon Sep 17 00:00:00 2001
From: Michael Dailey <michael.dailey@provartesting.com>
Date: Wed, 22 Apr 2026 15:04:25 -0500
Subject: [PATCH 03/12] PDX-0: test: add unit tests for migration and loop MCP
 prompts; fix auth test lint

Req: CLAUDE.md requires unit tests for new MCP functionality covering registration, argument interpolation, and optional arg handling
Fix: Add migrationPrompts.test.ts (16 tests) and loopPrompts.test.ts (24 tests); add eslint-disable camelcase to auth status test for expires_at fields

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 test/unit/commands/provar/auth/status.test.ts |   1 +
 test/unit/mcp/loopPrompts.test.ts             | 263 ++++++++++++++++++
 test/unit/mcp/migrationPrompts.test.ts        | 163 +++++++++++
 3 files changed, 427 insertions(+)
 create mode 100644 test/unit/mcp/loopPrompts.test.ts
 create mode 100644 test/unit/mcp/migrationPrompts.test.ts

diff --git a/test/unit/commands/provar/auth/status.test.ts b/test/unit/commands/provar/auth/status.test.ts
index c6763c44..99621ced 100644
--- a/test/unit/commands/provar/auth/status.test.ts
+++ b/test/unit/commands/provar/auth/status.test.ts
@@ -5,6 +5,7 @@
  * For full license text, see LICENSE.md file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 
+/* eslint-disable camelcase */
 import { strict as assert } from 'node:assert';
 import fs from 'node:fs';
 import os from 'node:os';
diff --git a/test/unit/mcp/loopPrompts.test.ts b/test/unit/mcp/loopPrompts.test.ts
new file mode 100644
index 00000000..04edbdc4
--- /dev/null
+++ b/test/unit/mcp/loopPrompts.test.ts
@@ -0,0 +1,263 @@
+/*
+ * Copyright (c) 2024 Provar Limited.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.md file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import { strict as assert } from 'node:assert';
+import { describe, it, beforeEach } from 'mocha';
+import {
+  registerLoopGeneratePrompt,
+  registerLoopFixPrompt,
+  registerLoopReviewPrompt,
+  registerLoopCoveragePrompt,
+} from '../../../src/mcp/prompts/loopPrompts.js';
+
+// ── Minimal McpServer mock ─────────────────────────────────────────────────────
+
+type PromptHandler = (args: Record<string, unknown>) => {
+  messages: Array<{ role: string; content: { type: string; text: string } }>;
+};
+
+interface PromptRegistration {
+  name: string;
+  description: string;
+  handler: PromptHandler;
+}
+
+class MockMcpServer {
+  public registrations: PromptRegistration[] = [];
+
+  public prompt(name: string, description: string, _schema: unknown, handler: PromptHandler): void {
+    this.registrations.push({ name, description, handler });
+  }
+
+  public call(name: string, args: Record<string, unknown>): ReturnType<PromptHandler> {
+    const reg = this.registrations.find((r) => r.name === name);
+    if (!reg) throw new Error(`Prompt not registered: ${name}`);
+    return reg.handler(args);
+  }
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+function getMessageText(result: ReturnType<PromptHandler>): string {
+  assert.ok(result.messages.length > 0, 'Expected at least one message');
+  assert.equal(result.messages[0].role, 'user');
+  assert.equal(result.messages[0].content.type, 'text');
+  return result.messages[0].content.text;
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────────
+
+let server: MockMcpServer;
+
+beforeEach(() => {
+  server = new MockMcpServer();
+  registerLoopGeneratePrompt(server as never);
+  registerLoopFixPrompt(server as never);
+  registerLoopReviewPrompt(server as never);
+  registerLoopCoveragePrompt(server as never);
+});
+
+describe('loopPrompts — registration', () => {
+  it('registers all 4 loop prompts', () => {
+    assert.equal(server.registrations.length, 4);
+  });
+
+  it('registers provar.loop.generate', () => {
+    const reg = server.registrations.find((r) => r.name === 'provar.loop.generate');
+    assert.ok(reg, 'provar.loop.generate should be registered');
+    assert.ok(
+      reg.description.includes('user story') || reg.description.includes('Generate'),
+      'description should describe generation use case'
+    );
+  });
+
+  it('registers provar.loop.fix', () => {
+    const reg = server.registrations.find((r) => r.name === 'provar.loop.fix');
+    assert.ok(reg, 'provar.loop.fix should be registered');
+    assert.ok(reg.description.toLowerCase().includes('fix'), 'description should describe fix use case');
+  });
+
+  it('registers provar.loop.review', () => {
+    const reg = server.registrations.find((r) => r.name === 'provar.loop.review');
+    assert.ok(reg, 'provar.loop.review should be registered');
+    assert.ok(reg.description.toLowerCase().includes('review'), 'description should describe review use case');
+  });
+
+  it('registers provar.loop.coverage', () => {
+    const reg = server.registrations.find((r) => r.name === 'provar.loop.coverage');
+    assert.ok(reg, 'provar.loop.coverage should be registered');
+    assert.ok(reg.description.toLowerCase().includes('coverage'), 'description should describe coverage use case');
+  });
+});
+
+describe('loopPrompts — provar.loop.generate', () => {
+  it('includes story text in message', () => {
+    const story = 'As a sales rep, I want to close an opportunity so revenue is recorded';
+    const result = server.call('provar.loop.generate', { story });
+    const text = getMessageText(result);
+    assert.ok(text.includes(story), 'message should contain the story text');
+  });
+
+  it('includes corpus retrieval workflow step', () => {
+    const result = server.call('provar.loop.generate', { story: 'any story' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('provar.qualityhub.examples.retrieve'), 'should reference corpus tool');
+    assert.ok(text.includes('provar.testcase.validate'), 'should reference validator tool');
+  });
+
+  it('includes objectName in message when provided', () => {
+    const result = server.call('provar.loop.generate', { story: 'any', objectName: 'Opportunity' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('Opportunity'), 'message should include object name');
+  });
+
+  it('includes testName in message when provided', () => {
+    const result = server.call('provar.loop.generate', { story: 'any', testName: 'CloseOpportunity' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('CloseOpportunity'), 'message should include target test name');
+  });
+
+  it('uses projectPath hint when provided', () => {
+    const result = server.call('provar.loop.generate', { story: 'any', projectPath: '/my/project' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('/my/project'), 'message should include project path');
+  });
+
+  it('falls back to ask-user hint when projectPath is omitted', () => {
+    const result = server.call('provar.loop.generate', { story: 'any' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('Ask the user'), 'message should prompt to ask for project path');
+  });
+});
+
+describe('loopPrompts — provar.loop.fix', () => {
+  it('includes testcasePath in message', () => {
+    const result = server.call('provar.loop.fix', {
+      testcasePath: '/provar/tests/CloseOpportunity.testcase',
+      rcaOutput: 'STEP FAILED: element not found',
+    });
+    const text = getMessageText(result);
+    assert.ok(text.includes('/provar/tests/CloseOpportunity.testcase'), 'message should include file path');
+  });
+
+  it('includes rcaOutput in message', () => {
+    const result = server.call('provar.loop.fix', {
+      testcasePath: '/any/path.testcase',
+      rcaOutput: 'STEP FAILED: assertion mismatch on field Amount',
+    });
+    const text = getMessageText(result);
+    assert.ok(text.includes('assertion mismatch on field Amount'), 'message should include RCA output');
+  });
+
+  it('includes corpus retrieval and validation in workflow', () => {
+    const result = server.call('provar.loop.fix', {
+      testcasePath: '/any/path.testcase',
+      rcaOutput: 'any failure',
+    });
+    const text = getMessageText(result);
+    assert.ok(text.includes('provar.qualityhub.examples.retrieve'), 'should reference corpus tool');
+    assert.ok(text.includes('provar.testcase.validate'), 'should reference validator tool');
+  });
+
+  it('starts workflow by reading the file', () => {
+    const result = server.call('provar.loop.fix', {
+      testcasePath: '/provar/tests/Test.testcase',
+      rcaOutput: 'error',
+    });
+    const text = getMessageText(result);
+    assert.ok(text.includes('/provar/tests/Test.testcase'), 'workflow begin instruction should reference the path');
+  });
+});
+
+describe('loopPrompts — provar.loop.review', () => {
+  it('includes testcasePath in message', () => {
+    const result = server.call('provar.loop.review', {
+      testcasePath: '/provar/tests/CreateLead.testcase',
+    });
+    const text = getMessageText(result);
+    assert.ok(text.includes('/provar/tests/CreateLead.testcase'), 'message should include file path');
+  });
+
+  it('includes review quality checklist categories', () => {
+    const result = server.call('provar.loop.review', {
+      testcasePath: '/any/path.testcase',
+    });
+    const text = getMessageText(result);
+    assert.ok(text.includes('Coverage') || text.includes('UiAssert'), 'message should include quality checklist');
+    assert.ok(text.includes('provar.testcase.validate'), 'should reference validator tool');
+  });
+
+  it('includes corpus retrieval step', () => {
+    const result = server.call('provar.loop.review', { testcasePath: '/any/path.testcase' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('provar.qualityhub.examples.retrieve'), 'should reference corpus tool');
+  });
+
+  it('includes projectPath in message when provided', () => {
+    const result = server.call('provar.loop.review', {
+      testcasePath: '/any/path.testcase',
+      projectPath: '/my/project',
+    });
+    const text = getMessageText(result);
+    assert.ok(text.includes('/my/project'), 'message should include project path');
+  });
+});
+
+describe('loopPrompts — provar.loop.coverage', () => {
+  it('includes objectName in message', () => {
+    const result = server.call('provar.loop.coverage', {
+      objectName: 'Opportunity',
+      projectPath: '/my/project',
+    });
+    const text = getMessageText(result);
+    assert.ok(text.includes('Opportunity'), 'message should include the object name');
+  });
+
+  it('includes projectPath in message', () => {
+    const result = server.call('provar.loop.coverage', {
+      objectName: 'Lead',
+      projectPath: '/provar/MyProject',
+    });
+    const text = getMessageText(result);
+    assert.ok(text.includes('/provar/MyProject'), 'message should include project path');
+  });
+
+  it('includes coverage matrix categories', () => {
+    const result = server.call('provar.loop.coverage', {
+      objectName: 'Account',
+      projectPath: '/any',
+    });
+    const text = getMessageText(result);
+    assert.ok(
+      text.includes('ApexCreateObject') || text.includes('API'),
+      'message should reference API coverage categories'
+    );
+  });
+
+  it('includes Quality Hub query step when targetOrg provided', () => {
+    const result = server.call('provar.loop.coverage', {
+      objectName: 'Contact',
+      projectPath: '/any',
+      targetOrg: 'my-org-alias',
+    });
+    const text = getMessageText(result);
+    assert.ok(
+      text.includes('provar.qualityhub.testcase.retrieve') || text.includes('my-org-alias'),
+      'message should include Quality Hub retrieval when targetOrg provided'
+    );
+  });
+
+  it('omits Quality Hub query step when targetOrg is not provided', () => {
+    const result = server.call('provar.loop.coverage', {
+      objectName: 'Contact',
+      projectPath: '/any',
+    });
+    const text = getMessageText(result);
+    // When no targetOrg, the step 2 should be corpus retrieval, not QH testcase retrieve
+    assert.ok(text.includes('provar.qualityhub.examples.retrieve'), 'should still include corpus retrieval');
+  });
+});
diff --git a/test/unit/mcp/migrationPrompts.test.ts b/test/unit/mcp/migrationPrompts.test.ts
new file mode 100644
index 00000000..cb7a8183
--- /dev/null
+++ b/test/unit/mcp/migrationPrompts.test.ts
@@ -0,0 +1,163 @@
+/*
+ * Copyright (c) 2024 Provar Limited.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.md file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import { strict as assert } from 'node:assert';
+import { describe, it, beforeEach } from 'mocha';
+import {
+  registerCrtMigrationPrompt,
+  registerSeleniumMigrationPrompt,
+  registerPlaywrightMigrationPrompt,
+} from '../../../src/mcp/prompts/migrationPrompts.js';
+
+// ── Minimal McpServer mock ─────────────────────────────────────────────────────
+
+type PromptHandler = (args: Record<string, unknown>) => {
+  messages: Array<{ role: string; content: { type: string; text: string } }>;
+};
+
+interface PromptRegistration {
+  name: string;
+  description: string;
+  handler: PromptHandler;
+}
+
+class MockMcpServer {
+  public registrations: PromptRegistration[] = [];
+
+  public prompt(name: string, description: string, _schema: unknown, handler: PromptHandler): void {
+    this.registrations.push({ name, description, handler });
+  }
+
+  public call(name: string, args: Record<string, unknown>): ReturnType<PromptHandler> {
+    const reg = this.registrations.find((r) => r.name === name);
+    if (!reg) throw new Error(`Prompt not registered: ${name}`);
+    return reg.handler(args);
+  }
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+function getMessageText(result: ReturnType<PromptHandler>): string {
+  assert.ok(result.messages.length > 0, 'Expected at least one message');
+  assert.equal(result.messages[0].role, 'user');
+  assert.equal(result.messages[0].content.type, 'text');
+  return result.messages[0].content.text;
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────────
+
+let server: MockMcpServer;
+
+beforeEach(() => {
+  server = new MockMcpServer();
+  registerCrtMigrationPrompt(server as never);
+  registerSeleniumMigrationPrompt(server as never);
+  registerPlaywrightMigrationPrompt(server as never);
+});
+
+describe('migrationPrompts — registration', () => {
+  it('registers provar.migrate.crt', () => {
+    const reg = server.registrations.find((r) => r.name === 'provar.migrate.crt');
+    assert.ok(reg, 'provar.migrate.crt should be registered');
+    assert.ok(reg.description.includes('CRT'), 'description should mention CRT');
+  });
+
+  it('registers provar.migrate.selenium', () => {
+    const reg = server.registrations.find((r) => r.name === 'provar.migrate.selenium');
+    assert.ok(reg, 'provar.migrate.selenium should be registered');
+    assert.ok(reg.description.includes('Selenium'), 'description should mention Selenium');
+  });
+
+  it('registers provar.migrate.playwright', () => {
+    const reg = server.registrations.find((r) => r.name === 'provar.migrate.playwright');
+    assert.ok(reg, 'provar.migrate.playwright should be registered');
+    assert.ok(reg.description.includes('Playwright'), 'description should mention Playwright');
+  });
+
+  it('registers all 3 migration prompts', () => {
+    assert.equal(server.registrations.length, 3);
+  });
+});
+
+describe('migrationPrompts — provar.migrate.crt', () => {
+  it('includes source content in message', () => {
+    const result = server.call('provar.migrate.crt', { source: 'Step 1: ClickText Accounts' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('Step 1: ClickText Accounts'), 'message should contain source content');
+  });
+
+  it('includes CRT context in message', () => {
+    const result = server.call('provar.migrate.crt', { source: 'Step 1: ClickText Accounts' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('ClickText'), 'message should include CRT keyword context');
+  });
+
+  it('includes workflow steps in message', () => {
+    const result = server.call('provar.migrate.crt', { source: 'any source' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('provar.qualityhub.examples.retrieve'), 'message should reference corpus retrieval tool');
+    assert.ok(text.includes('provar.testcase.validate'), 'message should reference validator tool');
+  });
+
+  it('uses provided testName when present', () => {
+    const result = server.call('provar.migrate.crt', { source: 'any source', testName: 'MyCustomTest' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('MyCustomTest'), 'message should include provided testName');
+  });
+
+  it('falls back to inferred name when testName is omitted', () => {
+    const result = server.call('provar.migrate.crt', { source: 'any source' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('Infer the test case name'), 'message should instruct to infer name when testName omitted');
+  });
+
+  it('includes project path hint when projectPath provided', () => {
+    const result = server.call('provar.migrate.crt', { source: 'any', projectPath: '/my/provar/project' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('/my/provar/project'), 'message should include project path');
+  });
+
+  it('falls back to ask-user hint when projectPath is omitted', () => {
+    const result = server.call('provar.migrate.crt', { source: 'any' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('Ask the user'), 'message should prompt to ask user for project path');
+  });
+});
+
+describe('migrationPrompts — provar.migrate.selenium', () => {
+  it('includes source content in message', () => {
+    const result = server.call('provar.migrate.selenium', { source: 'driver.get("https://example.com")' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('driver.get'), 'message should contain source content');
+  });
+
+  it('includes Selenium context in message', () => {
+    const result = server.call('provar.migrate.selenium', { source: 'any' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('WebDriver'), 'message should include Selenium context');
+  });
+
+  it('includes workflow steps', () => {
+    const result = server.call('provar.migrate.selenium', { source: 'any' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('provar.qualityhub.examples.retrieve'), 'should reference corpus tool');
+  });
+});
+
+describe('migrationPrompts — provar.migrate.playwright', () => {
+  it('includes source content in message', () => {
+    const result = server.call('provar.migrate.playwright', { source: 'await page.goto("https://example.com")' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('page.goto'), 'message should contain source content');
+  });
+
+  it('includes Playwright context in message', () => {
+    const result = server.call('provar.migrate.playwright', { source: 'any' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('getByLabel'), 'message should include Playwright context');
+  });
+});

From b178528a1b4b6d55bdba75abb4bbae2571b5e2af Mon Sep 17 00:00:00 2001
From: Michael Dailey <michael.dailey@provartesting.com>
Date: Wed, 22 Apr 2026 15:05:06 -0500
Subject: [PATCH 04/12] PDX-0: feat(mcp): wire prompts and step-reference
 resource into MCP server
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Req: Phase 2 corpus feature — expose prompts via MCP protocol and serve canonical step reference as a resource at provar://docs/step-reference
Fix: Register prompts, add MCP resource with readFileSync, update compile script to bundle docs, sync server.json and bump to beta.8

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 package.json          |  5 +++--
 scripts/mcp-smoke.cjs | 42 ++++++++++++++++++++++++++++++++++++++++--
 server.json           | 21 +++++++++++++++++++++
 src/mcp/server.ts     | 43 +++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 107 insertions(+), 4 deletions(-)
 create mode 100644 server.json

diff --git a/package.json b/package.json
index 1d25ee36..6aeaf3c1 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,8 @@
 {
   "name": "@provartesting/provardx-cli",
   "description": "A plugin for the Salesforce CLI to orchestrate testing activities and report quality metrics to Provar Quality Hub",
-  "version": "1.5.0-beta.7",
+  "version": "1.5.0-beta.8",
+  "mcpName": "io.github.provartesting/provar",
   "license": "BSD-3-Clause",
   "plugins": [
     "@provartesting/provardx-plugins-automation",
@@ -145,7 +146,7 @@
       ]
     },
     "compile": {
-      "command": "tsc -p . --pretty --incremental && shx mkdir -p lib/mcp/rules && shx cp src/mcp/rules/*.json lib/mcp/rules/",
+      "command": "tsc -p . --pretty --incremental && shx mkdir -p lib/mcp/rules && shx cp src/mcp/rules/*.json lib/mcp/rules/ && shx mkdir -p lib/mcp/docs && shx cp docs/PROVAR_TEST_STEP_REFERENCE.md lib/mcp/docs/",
       "files": [
         "src/**/*.ts",
         "src/mcp/rules/*.json",
diff --git a/scripts/mcp-smoke.cjs b/scripts/mcp-smoke.cjs
index 15b7500f..f9eff650 100644
--- a/scripts/mcp-smoke.cjs
+++ b/scripts/mcp-smoke.cjs
@@ -312,6 +312,44 @@ async function runTests() {
     n: 3,
   });
 
+  // ── 40. prompts/list ──────────────────────────────────────────────────────
+  await send('prompts/list', {});
+
+  // ── 41–43. provar.migrate.* prompts ──────────────────────────────────────
+  await rpc('provar.migrate.crt (prompt)', 'prompts/get', {
+    name: 'provar.migrate.crt',
+    arguments: { source: 'Step 1: ClickText Accounts' },
+  });
+  await rpc('provar.migrate.selenium (prompt)', 'prompts/get', {
+    name: 'provar.migrate.selenium',
+    arguments: { source: 'driver.get("https://example.com")' },
+  });
+  await rpc('provar.migrate.playwright (prompt)', 'prompts/get', {
+    name: 'provar.migrate.playwright',
+    arguments: { source: 'await page.goto("https://example.com")' },
+  });
+
+  // ── 44–47. provar.loop.* prompts ─────────────────────────────────────────
+  await rpc('provar.loop.generate (prompt)', 'prompts/get', {
+    name: 'provar.loop.generate',
+    arguments: { story: 'As a sales rep I want to close an opportunity so that revenue is recorded.' },
+  });
+  await rpc('provar.loop.fix (prompt)', 'prompts/get', {
+    name: 'provar.loop.fix',
+    arguments: {
+      testcasePath: '/tmp/CloseOpportunity.testcase',
+      rcaOutput: 'STEP FAILED: Click the Save button — element not found',
+    },
+  });
+  await rpc('provar.loop.review (prompt)', 'prompts/get', {
+    name: 'provar.loop.review',
+    arguments: { testcasePath: '/tmp/CloseOpportunity.testcase' },
+  });
+  await rpc('provar.loop.coverage (prompt)', 'prompts/get', {
+    name: 'provar.loop.coverage',
+    arguments: { objectName: 'Opportunity', projectPath: '/tmp/provar-project' },
+  });
+
   server.stdin.end();
 }
 
@@ -320,8 +358,8 @@ async function runTests() {
 // ----------------------------------------------------------------------------
 server.on('close', () => {
   clearTimeout(overallTimer);
-  // initialize + tools/list + 37 tools (setup excluded from default count)
-  const TOTAL_EXPECTED = 39 + (INCLUDE_SETUP ? 1 : 0);
+  // initialize + tools/list + 37 tools + prompts/list + 7 prompts/get (setup excluded from default count)
+  const TOTAL_EXPECTED = 47 + (INCLUDE_SETUP ? 1 : 0);
   let passed = 0;
   let failed = 0;
 
diff --git a/server.json b/server.json
new file mode 100644
index 00000000..adae97c4
--- /dev/null
+++ b/server.json
@@ -0,0 +1,21 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.provartesting/provar",
+  "description": "Provar MCP server — AI-powered Salesforce test automation. Generate, validate, and migrate Provar test cases; connect to Quality Hub for test corpus retrieval and test run orchestration.",
+  "repository": {
+    "url": "https://github.com/ProvarTesting/provardx-cli",
+    "source": "github"
+  },
+  "version": "1.5.0-beta.8",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@provartesting/provardx-cli",
+      "version": "1.5.0-beta.8",
+      "transport": {
+        "type": "stdio"
+      },
+      "runtimeArguments": ["provar", "mcp", "start", "--allowed-paths", "${workspaceFolder}"]
+    }
+  ]
+}
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index 33d42474..8520a94a 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -6,6 +6,9 @@
  */
 
 import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { log } from './logging/logger.js';
@@ -29,6 +32,7 @@ import { registerAllAntTools } from './tools/antTools.js';
 import { registerAllRcaTools } from './tools/rcaTools.js';
 import { registerAllTestPlanTools } from './tools/testPlanTools.js';
 import { registerAllNitroXTools } from './tools/nitroXTools.js';
+import { registerAllPrompts } from './prompts/index.js';
 
 export interface ServerConfig {
   allowedPaths: string[];
@@ -77,5 +81,44 @@ export function createProvarMcpServer(config: ServerConfig): McpServer {
   registerAllTestPlanTools(server, config);
   registerAllNitroXTools(server, config);
 
+  // ── Provar prompts ───────────────────────────────────────────────────────────
+  registerAllPrompts(server);
+
+  // ── Documentation resources ──────────────────────────────────────────────────
+  const docsDir = join(dirname(fileURLToPath(import.meta.url)), 'docs');
+  server.resource(
+    'provar-step-reference',
+    'provar://docs/step-reference',
+    {
+      description:
+        'Canonical reference for all Provar XML test step API IDs, argument formats, validation rules, and corpus-verified examples. Use this to understand correct step structure when generating or reviewing test cases.',
+      mimeType: 'text/markdown',
+    },
+    () => {
+      try {
+        const content = readFileSync(join(docsDir, 'PROVAR_TEST_STEP_REFERENCE.md'), 'utf-8');
+        return {
+          contents: [
+            {
+              uri: 'provar://docs/step-reference',
+              mimeType: 'text/markdown',
+              text: content,
+            },
+          ],
+        };
+      } catch {
+        return {
+          contents: [
+            {
+              uri: 'provar://docs/step-reference',
+              mimeType: 'text/markdown',
+              text: '# Provar Test Step Reference\n\nReference doc not found. Run `yarn compile` to build.',
+            },
+          ],
+        };
+      }
+    }
+  );
+
   return server;
 }

From 084e72baf0eb14fa39bb1e95f847ab15e69c2b0e Mon Sep 17 00:00:00 2001
From: Michael Dailey <michael.dailey@provartesting.com>
Date: Wed, 22 Apr 2026 15:13:55 -0500
Subject: [PATCH 05/12] PDX-0: docs: update documentation for v1.5.0-beta.8
 prompts + step-reference
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Req: Phase 2 migration corpus feature — document 7 new MCP prompts (provar.migrate.crt/selenium/playwright, provar.loop.generate/fix/review/coverage) and the provar://docs/step-reference MCP resource
Fix: Add MCP Prompts section and MCP Resources section to docs/mcp.md, update README tool count blurb, add Scenario 11 migration evaluation scenario to mcp-pilot-guide.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md               |   2 +-
 docs/mcp-pilot-guide.md |  28 ++++++++
 docs/mcp.md             | 149 ++++++++++++++++++++++++++++++++++++++++
 3 files changed, 178 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 92d62aaf..7ea495e0 100644
--- a/README.md
+++ b/README.md
@@ -73,7 +73,7 @@ claude mcp add provar -s user -- sf provar mcp start --allowed-paths /path/to/yo
 
 > **Windows (Claude Desktop):** Use `sf.cmd` instead of `sf` if the server fails to start.
 
-📖 **[docs/mcp.md](https://github.com/ProvarTesting/provardx-cli/blob/main/docs/mcp.md) — full setup, all 35+ tools, troubleshooting.**
+📖 **[docs/mcp.md](https://github.com/ProvarTesting/provardx-cli/blob/main/docs/mcp.md) — full setup, all 35+ tools, 7 MCP prompts, troubleshooting.**
 
 ---
 
diff --git a/docs/mcp-pilot-guide.md b/docs/mcp-pilot-guide.md
index 9fa7384c..2ca3fc78 100644
--- a/docs/mcp-pilot-guide.md
+++ b/docs/mcp-pilot-guide.md
@@ -411,6 +411,34 @@ NitroX is Provar's Hybrid Model for locators — it maps Salesforce component-ba
 
 ---
 
+### Scenario 11: Migration Prompts — Convert a Test from Another Framework
+
+**Goal:** Use the MCP migration prompts to convert a test written in CRT, Selenium, or Playwright into a Provar XML test case in one step.
+
+**Prerequisites:** A Provar project on disk and (optional) a Provar API key for corpus grounding.
+
+**CRT migration** — paste a QWord step sequence or `.robot` file:
+
+> "Use the provar.migrate.crt prompt to migrate the following CRT test to Provar: `Step 1: OpenBrowser https://login.salesforce.com` `Step 2: TypeText Username myuser@example.com` `Step 3: ClickText Log In` `Step 4: VerifyText Home`"
+
+**Selenium migration:**
+
+> "Use the provar.migrate.selenium prompt to migrate my JUnit test that creates an Opportunity in Salesforce. The test calls `driver.findElement(By.id('opp-name')).sendKeys('Q4 Deal')` and `driver.findElement(By.id('save-btn')).click()`."
+
+**Playwright migration:**
+
+> "Use the provar.migrate.playwright prompt to convert this Playwright test: `await page.getByLabel('Close Date').fill('12/31/2025'); await page.getByRole('button', { name: 'Save' }).click();`"
+
+**What to look for:**
+
+- The AI calls `provar.qualityhub.examples.retrieve` first to retrieve grounding examples (if an API key is configured)
+- A valid Provar XML test case is generated, using `<apiCall>` steps that correspond to the source test's actions
+- Salesforce login/navigation is omitted from the generated XML (Provar handles this via Connection Manager)
+- `provar.testcase.validate` is called on the result and returns `is_valid: true`
+- Any steps that could not be mapped are left as `<!-- TODO: manual step -->` comments in the XML
+
+---
+
 ## Security Model
 
 ### What the server does
diff --git a/docs/mcp.md b/docs/mcp.md
index da025c98..f238d210 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -57,6 +57,18 @@ The Provar DX CLI ships with a built-in **Model Context Protocol (MCP) server**
   - [Quality Hub API tools](#quality-hub-api-tools)
     - [provar.qualityhub.examples.retrieve](#provarqualityhubexamplesretrieve)
   - [Org metadata via Salesforce Hosted MCP](#org-metadata-via-salesforce-hosted-mcp)
+- [MCP Prompts](#mcp-prompts)
+  - [Migration prompts](#migration-prompts)
+    - [provar.migrate.crt](#provarmigratecrt)
+    - [provar.migrate.selenium](#provarmigratselenium)
+    - [provar.migrate.playwright](#provarmigrationplaywright)
+  - [AI loop prompts](#ai-loop-prompts)
+    - [provar.loop.generate](#provarloopgenerate)
+    - [provar.loop.fix](#provarloopfix)
+    - [provar.loop.review](#provarloopreview)
+    - [provar.loop.coverage](#provarloopcount)
+- [MCP Resources](#mcp-resources)
+  - [provar://docs/step-reference](#provardocsstep-reference)
 - [AI loop pattern](#ai-loop-pattern)
 - [Quality scores explained](#quality-scores-explained)
 - [API compatibility — `xml` vs `xml_content`](#api-compatibility--xml-vs-xml_content)
@@ -1552,6 +1564,143 @@ The SF Hosted MCP uses per-user OAuth 2.0, respects field-level security and sha
 
 ---
 
+## MCP Prompts
+
+The Provar MCP server registers **7 MCP prompts** that pre-wire the tool chain into turnkey workflows. AI clients that support MCP prompts (Claude Desktop, Claude Code) can invoke them directly by name instead of manually orchestrating the underlying tool sequence.
+
+---
+
+### Migration prompts
+
+These prompts convert tests from other frameworks into Provar XML. Each prompt:
+
+1. Calls `provar.qualityhub.examples.retrieve` with keywords from the source test to load few-shot grounding examples.
+2. Generates a Provar XML test case using those examples as structural context.
+3. Writes the file to the target project.
+4. Calls `provar.testcase.validate` and iterates until the output is clean.
+
+---
+
+#### `provar.migrate.crt`
+
+Convert a Copado Robotic Testing (CRT) test — either a QWord step sequence or a Robot Framework `.robot` file — into a Provar XML test case.
+
+**Arguments**
+
+| Parameter     | Type   | Required | Description                                                                      |
+| ------------- | ------ | -------- | -------------------------------------------------------------------------------- |
+| `source`      | string | yes      | The CRT test content. Accepts a numbered QWord sequence or a full `.robot` file. |
+| `projectPath` | string | no       | Absolute path to the Provar project root for writing the output file.            |
+| `testName`    | string | no       | Target test case name. Inferred from the source if omitted.                      |
+
+---
+
+#### `provar.migrate.selenium`
+
+Convert a Selenium WebDriver test (Java, Python, or JavaScript) that targets a Salesforce org into a Provar XML test case.
+
+**Arguments**
+
+| Parameter     | Type   | Required | Description                                                                    |
+| ------------- | ------ | -------- | ------------------------------------------------------------------------------ |
+| `source`      | string | yes      | The Selenium test file content (JUnit/TestNG, unittest/pytest, or Jest/Mocha). |
+| `projectPath` | string | no       | Absolute path to the Provar project root for writing the output file.          |
+| `testName`    | string | no       | Target test case name. Inferred from the class/method name if omitted.         |
+
+---
+
+#### `provar.migrate.playwright`
+
+Convert a Playwright test (TypeScript or JavaScript) that targets a Salesforce org into a Provar XML test case.
+
+**Arguments**
+
+| Parameter     | Type   | Required | Description                                                                     |
+| ------------- | ------ | -------- | ------------------------------------------------------------------------------- |
+| `source`      | string | yes      | The Playwright test file content (`@playwright/test` or `playwright` library).  |
+| `projectPath` | string | no       | Absolute path to the Provar project root for writing the output file.           |
+| `testName`    | string | no       | Target test case name. Inferred from the `test()` block description if omitted. |
+
+---
+
+### AI loop prompts
+
+These prompts drive the iterative test generation and quality improvement loop.
+
+---
+
+#### `provar.loop.generate`
+
+Generate a Provar XML test case from a user story or acceptance criteria. Retrieves corpus examples for grounding, generates the test, writes it to the project, then validates it.
+
+**Arguments**
+
+| Parameter     | Type   | Required | Description                                                                           |
+| ------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
+| `story`       | string | yes      | The user story or acceptance criteria. Include the Salesforce object and action.      |
+| `projectPath` | string | no       | Absolute path to the Provar project root.                                             |
+| `testName`    | string | no       | Output test case file name (without extension). Inferred from the story if omitted.   |
+| `objectName`  | string | no       | Primary Salesforce object under test (e.g. `"Opportunity"`). Scopes the corpus query. |
+
+---
+
+#### `provar.loop.fix`
+
+Fix a failing Provar test case using RCA output. Reads the current XML, interprets the failure, applies targeted fixes, and re-validates until the test passes.
+
+**Arguments**
+
+| Parameter      | Type   | Required | Description                                                            |
+| -------------- | ------ | -------- | ---------------------------------------------------------------------- |
+| `testcasePath` | string | yes      | Absolute path to the `.testcase` file to fix.                          |
+| `rcaOutput`    | string | yes      | The failure message or RCA output from `provar.testrun.rca`.           |
+| `projectPath`  | string | no       | Absolute path to the Provar project root (used for context if needed). |
+
+---
+
+#### `provar.loop.review`
+
+Review a Provar test case for quality, coverage, and best practices. Returns a scored report with specific improvement suggestions.
+
+**Arguments**
+
+| Parameter      | Type   | Required | Description                                      |
+| -------------- | ------ | -------- | ------------------------------------------------ |
+| `testcasePath` | string | yes      | Absolute path to the `.testcase` file to review. |
+| `projectPath`  | string | no       | Absolute path to the Provar project root.        |
+
+---
+
+#### `provar.loop.coverage`
+
+Analyse coverage gaps for a Salesforce object or feature area. Inspects the project's existing tests, identifies what is not covered, and generates new test cases to close the gaps.
+
+**Arguments**
+
+| Parameter     | Type   | Required | Description                                                                       |
+| ------------- | ------ | -------- | --------------------------------------------------------------------------------- |
+| `objectName`  | string | yes      | Primary Salesforce object to check coverage for (e.g. `"Opportunity"`, `"Lead"`). |
+| `projectPath` | string | yes      | Absolute path to the Provar project root.                                         |
+
+---
+
+## MCP Resources
+
+The Provar MCP server also exposes one **MCP resource** — structured reference content that AI clients can read directly from the server.
+
+---
+
+### `provar://docs/step-reference`
+
+Canonical reference for all Provar XML test step API IDs, argument formats, validation rules, and corpus-verified examples. AI clients can read this resource to understand correct step structure when generating or reviewing test cases — without needing to fetch it from disk.
+
+**URI:** `provar://docs/step-reference`  
+**MIME type:** `text/markdown`
+
+The resource content is the same as `docs/PROVAR_TEST_STEP_REFERENCE.md` in this repository, compiled into the package at build time.
+
+---
+
 ## AI loop pattern
 
 The automation tools are designed to support an **AI-driven fix loop**: an agent can iteratively improve test quality without leaving the chat session.

From db6aa1fc7f700cfee3b39eb02942656318bd2959 Mon Sep 17 00:00:00 2001
From: Michael Dailey <michael.dailey@provartesting.com>
Date: Wed, 22 Apr 2026 15:35:42 -0500
Subject: [PATCH 06/12] =?UTF-8?q?PDX-0:=20fix:=20address=20PR=20review=20c?=
 =?UTF-8?q?omments=20=E2=80=94=20ToC=20anchors,=20targetOrg=20docs,=20esli?=
 =?UTF-8?q?nt=20narrowing?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Req: Fix three Copilot PR review findings: broken ToC anchor fragments in docs/mcp.md,
missing targetOrg argument in provar.loop.coverage docs table, and overly broad
eslint-disable camelcase in auth status test.
Fix: Corrected anchor hrefs (#provarmigrateselenium, #provarmigrateplaywright,
#provarloopcoverage), added targetOrg row to arguments table, narrowed eslint
disable to two eslint-disable-next-line comments on the specific expires_at lines.
---
 docs/mcp.md                                   | 15 ++++++++-------
 test/unit/commands/provar/auth/status.test.ts |  3 ++-
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/docs/mcp.md b/docs/mcp.md
index f238d210..1ba63eea 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -60,13 +60,13 @@ The Provar DX CLI ships with a built-in **Model Context Protocol (MCP) server**
 - [MCP Prompts](#mcp-prompts)
   - [Migration prompts](#migration-prompts)
     - [provar.migrate.crt](#provarmigratecrt)
-    - [provar.migrate.selenium](#provarmigratselenium)
-    - [provar.migrate.playwright](#provarmigrationplaywright)
+    - [provar.migrate.selenium](#provarmigrateselenium)
+    - [provar.migrate.playwright](#provarmigrateplaywright)
   - [AI loop prompts](#ai-loop-prompts)
     - [provar.loop.generate](#provarloopgenerate)
     - [provar.loop.fix](#provarloopfix)
     - [provar.loop.review](#provarloopreview)
-    - [provar.loop.coverage](#provarloopcount)
+    - [provar.loop.coverage](#provarloopcoverage)
 - [MCP Resources](#mcp-resources)
   - [provar://docs/step-reference](#provardocsstep-reference)
 - [AI loop pattern](#ai-loop-pattern)
@@ -1677,10 +1677,11 @@ Analyse coverage gaps for a Salesforce object or feature area. Inspects the proj
 
 **Arguments**
 
-| Parameter     | Type   | Required | Description                                                                       |
-| ------------- | ------ | -------- | --------------------------------------------------------------------------------- |
-| `objectName`  | string | yes      | Primary Salesforce object to check coverage for (e.g. `"Opportunity"`, `"Lead"`). |
-| `projectPath` | string | yes      | Absolute path to the Provar project root.                                         |
+| Parameter     | Type   | Required | Description                                                                                                                                                                                |
+| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `objectName`  | string | yes      | Primary Salesforce object to check coverage for (e.g. `"Opportunity"`, `"Lead"`).                                                                                                          |
+| `projectPath` | string | yes      | Absolute path to the Provar project root.                                                                                                                                                  |
+| `targetOrg`   | string | no       | Salesforce org alias or username. When provided, existing Quality Hub test cases for this object are retrieved via `provar.qualityhub.testcase.retrieve` before the coverage gap analysis. |
 
 ---
 
diff --git a/test/unit/commands/provar/auth/status.test.ts b/test/unit/commands/provar/auth/status.test.ts
index 99621ced..fbfedc0e 100644
--- a/test/unit/commands/provar/auth/status.test.ts
+++ b/test/unit/commands/provar/auth/status.test.ts
@@ -5,7 +5,6 @@
  * For full license text, see LICENSE.md file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 
-/* eslint-disable camelcase */
 import { strict as assert } from 'node:assert';
 import fs from 'node:fs';
 import os from 'node:os';
@@ -167,9 +166,11 @@ describe('auth status — expiry warning logic', () => {
 
   it('writeCredentials stores expires_at and readStoredCredentials returns it', () => {
     const expires = new Date(NOW + 30 * 24 * 60 * 60 * 1000).toISOString();
+    // eslint-disable-next-line camelcase
     writeCredentials('pv_k_expirytestkey1', 'pv_k_expiry', 'manual', { expires_at: expires });
     const stored = readStoredCredentials();
     assert.ok(stored, 'credentials should exist');
+    // eslint-disable-next-line camelcase
     assert.equal(stored?.expires_at, expires);
   });
 });

From ba50b9b09ceeffdace63db5e123a938dca94abff Mon Sep 17 00:00:00 2001
From: Michael Dailey <michael.dailey@provartesting.com>
Date: Wed, 22 Apr 2026 15:36:52 -0500
Subject: [PATCH 07/12] PDX-0: feat(mcp): add step-reference fallback when
 corpus retrieval returns no examples

Req: When provar.qualityhub.examples.retrieve degrades gracefully (API unavailable,
unauthenticated, or rate-limited), AI agents had no alternative grounding source.
This left direct tool invocations and Copilot prompt users without format guidance.
Fix: Added CORPUS_FALLBACK_HINT to all four warning constants in the retrieve tool
so the hint surfaces regardless of how the tool is invoked. Updated migrationOrchestration
in migrationPrompts.ts, all corpus-retrieval steps in loopPrompts.ts, and all three
.github/prompts/*.prompt.md files to instruct agents to read provar://docs/step-reference
when count:0 + warning is returned.
---
 .github/prompts/crt-to-provar.prompt.md        |  1 +
 .github/prompts/playwright-to-provar.prompt.md |  1 +
 .github/prompts/selenium-to-provar.prompt.md   |  1 +
 src/mcp/prompts/loopPrompts.ts                 | 18 +++++++++++++++---
 src/mcp/prompts/migrationPrompts.ts            |  3 +++
 src/mcp/tools/qualityHubApiTools.ts            | 15 +++++++++++----
 6 files changed, 32 insertions(+), 7 deletions(-)

diff --git a/.github/prompts/crt-to-provar.prompt.md b/.github/prompts/crt-to-provar.prompt.md
index c67efbad..9aa99d4e 100644
--- a/.github/prompts/crt-to-provar.prompt.md
+++ b/.github/prompts/crt-to-provar.prompt.md
@@ -20,6 +20,7 @@ Robot Framework sections: `*** Keywords ***` = reusable blocks, `*** Test Cases
 ## Migration workflow
 
 1. **Get examples** — call `provar.qualityhub.examples.retrieve` with keywords that describe the test scenario (e.g. "create account", "close opportunity"). Use the returned XML examples as the sole reference for Provar format and step patterns.
+   If the response has `"count": 0` with a `"warning"` field (API unavailable or not configured), fall back: read the `provar://docs/step-reference` MCP resource for step types and attribute formats, then continue with generation based on that reference.
 2. **Generate** — produce valid Provar XML that captures the intent of the source test, based on the retrieved examples. Omit login/browser setup — Provar handles that via Connection Manager.
 3. **Write** — save the XML to the `tests/` directory in the Provar project.
 4. **Validate** — call `provar.testcase.validate` on the saved file. Fix any errors and re-validate until clean.
diff --git a/.github/prompts/playwright-to-provar.prompt.md b/.github/prompts/playwright-to-provar.prompt.md
index 2984907e..c56788d1 100644
--- a/.github/prompts/playwright-to-provar.prompt.md
+++ b/.github/prompts/playwright-to-provar.prompt.md
@@ -24,6 +24,7 @@ Common patterns to recognise:
 ## Migration workflow
 
 1. **Get examples** — call `provar.qualityhub.examples.retrieve` with keywords describing the test scenario (e.g. "create contact", "close opportunity"). Use the returned XML examples as the sole reference for Provar format and step patterns.
+   If the response has `"count": 0` with a `"warning"` field (API unavailable or not configured), fall back: read the `provar://docs/step-reference` MCP resource for step types and attribute formats, then continue with generation based on that reference.
 2. **Generate** — produce valid Provar XML based on the retrieved examples. Omit login/navigation setup — Provar handles Salesforce sessions via Connection Manager.
 3. **Write** — save the XML to the `tests/` directory in the Provar project.
 4. **Validate** — call `provar.testcase.validate` on the saved file. Fix any errors and re-validate until clean.
diff --git a/.github/prompts/selenium-to-provar.prompt.md b/.github/prompts/selenium-to-provar.prompt.md
index 3a46422c..6cee313b 100644
--- a/.github/prompts/selenium-to-provar.prompt.md
+++ b/.github/prompts/selenium-to-provar.prompt.md
@@ -21,6 +21,7 @@ Common patterns to recognise:
 ## Migration workflow
 
 1. **Get examples** — call `provar.qualityhub.examples.retrieve` with keywords describing the test scenario (e.g. "create opportunity", "convert lead"). Use the returned XML examples as the sole reference for Provar format and step patterns.
+   If the response has `"count": 0` with a `"warning"` field (API unavailable or not configured), fall back: read the `provar://docs/step-reference` MCP resource for step types and attribute formats, then continue with generation based on that reference.
 2. **Generate** — produce valid Provar XML based on the retrieved examples. Omit browser/login setup — Provar handles Salesforce sessions via Connection Manager.
 3. **Write** — save the XML to the `tests/` directory in the Provar project.
 4. **Validate** — call `provar.testcase.validate` on the saved file. Fix any errors and re-validate until clean.
diff --git a/src/mcp/prompts/loopPrompts.ts b/src/mcp/prompts/loopPrompts.ts
index b2bdd4c3..26702b0e 100644
--- a/src/mcp/prompts/loopPrompts.ts
+++ b/src/mcp/prompts/loopPrompts.ts
@@ -65,6 +65,9 @@ Follow these steps in order:
 2. **Get corpus examples** — call \`provar.qualityhub.examples.retrieve\` with the keywords you extracted
    (e.g. "close opportunity" or "create lead"). Use the returned XML examples as the sole reference for
    Provar step structure and argument patterns. Do not invent XML structure from prior knowledge.
+   If the response has \`"count": 0\` with a \`"warning"\` field (API unavailable or not configured),
+   fall back: read the \`provar://docs/step-reference\` MCP resource for step types and attribute
+   formats, then continue.
 
 3. **Map acceptance criteria to steps** — for each acceptance criterion, identify the corresponding Provar
    step type: field fills → UiDoAction (set), button clicks → UiDoAction (action), field checks →
@@ -160,6 +163,9 @@ Follow these steps in order:
 3. **Get corpus examples** — call \`provar.qualityhub.examples.retrieve\` with keywords describing the
    failing step's scenario (e.g. "close opportunity UiDoAction" or "assert field value UiAssert").
    Use the returned examples to verify the correct structure for the failing step type.
+   If the response has \`"count": 0\` with a \`"warning"\` field, fall back: read the
+   \`provar://docs/step-reference\` MCP resource for the correct attribute schema for the failing
+   step type, then continue.
 
 4. **Diagnose the root cause** — compare the failing step's XML against the corpus examples. Common issues:
    - Wrong interaction URI (action vs set vs file)
@@ -228,7 +234,9 @@ Follow these steps in order:
 
 3. **Get corpus examples** — call \`provar.qualityhub.examples.retrieve\` with keywords describing the
    test scenario (e.g. "create opportunity", "close opportunity"). Use the returned examples as a
-   quality baseline.
+   quality baseline. If the response has \`"count": 0\` with a \`"warning"\` field, fall back: read
+   the \`provar://docs/step-reference\` MCP resource for step type schemas, then continue the review
+   using that as the quality baseline.
 
 4. **Review for quality gaps** — check for each of the following, noting pass or fail:
 
@@ -332,9 +340,13 @@ ${
    coverage inventory.
 
 3. **Get corpus examples** — call \`provar.qualityhub.examples.retrieve\` with "${objectName.toLowerCase()}"
-   as the query to understand what test patterns exist in the corpus for this object.`
+   as the query to understand what test patterns exist in the corpus for this object.
+   If the response has \`"count": 0\` with a \`"warning"\` field, fall back: read the
+   \`provar://docs/step-reference\` MCP resource for step type schemas, then continue.`
     : `2. **Get corpus examples** — call \`provar.qualityhub.examples.retrieve\` with "${objectName.toLowerCase()}"
-   as the query to understand what test patterns exist in the corpus for this object.`
+   as the query to understand what test patterns exist in the corpus for this object.
+   If the response has \`"count": 0\` with a \`"warning"\` field, fall back: read the
+   \`provar://docs/step-reference\` MCP resource for step type schemas, then continue.`
 }
 
 ${targetOrg ? '4' : '3'}. **Build the coverage matrix** — define the standard test scenarios for "${objectName}":
diff --git a/src/mcp/prompts/migrationPrompts.ts b/src/mcp/prompts/migrationPrompts.ts
index d0fa6f28..db36abc8 100644
--- a/src/mcp/prompts/migrationPrompts.ts
+++ b/src/mcp/prompts/migrationPrompts.ts
@@ -68,6 +68,9 @@ Follow these steps in order:
 1. **Get corpus examples** — call \`provar.qualityhub.examples.retrieve\` with keywords that
    describe the source test's main scenario (e.g. "create opportunity", "close case", "convert lead").
    Use the returned examples as few-shot grounding for the Provar XML format and step patterns.
+   If the response has \`"count": 0\` with a \`"warning"\` field (API unavailable or not configured),
+   fall back: read the \`provar://docs/step-reference\` MCP resource for step types and attribute
+   formats, then continue with generation based on that reference.
 
 2. **Generate the test case** — produce a valid Provar XML test case that faithfully captures
    the intent of the source test. Base the structure entirely on the corpus examples, not on
diff --git a/src/mcp/tools/qualityHubApiTools.ts b/src/mcp/tools/qualityHubApiTools.ts
index e1b54f34..130645ec 100644
--- a/src/mcp/tools/qualityHubApiTools.ts
+++ b/src/mcp/tools/qualityHubApiTools.ts
@@ -19,21 +19,28 @@ import {
   REQUEST_ACCESS_URL,
 } from '../../services/qualityHub/client.js';
 
+const CORPUS_FALLBACK_HINT =
+  'Fallback: read the provar://docs/step-reference MCP resource for step types and attribute formats, then continue.';
+
 const CORPUS_ONBOARDING_WARNING =
   'Corpus retrieval skipped — no Provar API key configured. Continuing without example grounding.\n' +
   'To enable corpus retrieval: run sf provar auth login\n' +
-  `No account? Request access at: ${REQUEST_ACCESS_URL}`;
+  `No account? Request access at: ${REQUEST_ACCESS_URL}\n` +
+  CORPUS_FALLBACK_HINT;
 
 const CORPUS_AUTH_WARNING =
   'Corpus retrieval skipped — API key is invalid or expired. Continuing without example grounding.\n' +
-  `Run sf provar auth login to get a new key, or request access at: ${REQUEST_ACCESS_URL}`;
+  `Run sf provar auth login to get a new key, or request access at: ${REQUEST_ACCESS_URL}\n` +
+  CORPUS_FALLBACK_HINT;
 
 const CORPUS_RATE_LIMIT_WARNING =
-  'Corpus retrieval skipped — rate limit reached. Continuing without example grounding. Try again shortly.';
+  'Corpus retrieval skipped — rate limit reached. Continuing without example grounding. Try again shortly.\n' +
+  CORPUS_FALLBACK_HINT;
 
 const CORPUS_UNREACHABLE_WARNING =
   'Corpus retrieval skipped — API unreachable. Continuing without example grounding.\n' +
-  'Check your network connection or try again later.';
+  'Check your network connection or try again later.\n' +
+  CORPUS_FALLBACK_HINT;
 
 // ── Tool: provar.qualityhub.examples.retrieve ─────────────────────────────────
 

From 9ef4c4e3d4048047ecc4084bf30ed1edc21ddeaf Mon Sep 17 00:00:00 2001
From: Michael Dailey <michael.dailey@provartesting.com>
Date: Wed, 22 Apr 2026 15:51:16 -0500
Subject: [PATCH 08/12] PDX-0: chore(mcp): add title, websiteUrl, and icon to
 server.json for MCP registry listing

Req: MCP registry listing benefits from display name, docs URL, and branded icon
for client UI rendering. These are optional schema fields but expected by the
registry publisher and MCP clients.
Fix: Added title, websiteUrl pointing to docs/mcp.md, and icons referencing the
Provar automation icon at assets/icon.png via raw.githubusercontent.com HTTPS URL.
---
 assets/icon.png | Bin 0 -> 15777 bytes
 server.json     |   8 ++++++++
 2 files changed, 8 insertions(+)
 create mode 100644 assets/icon.png

diff --git a/assets/icon.png b/assets/icon.png
new file mode 100644
index 0000000000000000000000000000000000000000..f5b1738e5f01c39233f603f1bb43740e63186b52
GIT binary patch
literal 15777
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
K8kFeS6aEjR!m5)1

literal 0
HcmV?d00001

diff --git a/server.json b/server.json
index adae97c4..5eb7110e 100644
--- a/server.json
+++ b/server.json
@@ -1,7 +1,15 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.provartesting/provar",
+  "title": "Provar MCP Server",
   "description": "Provar MCP server — AI-powered Salesforce test automation. Generate, validate, and migrate Provar test cases; connect to Quality Hub for test corpus retrieval and test run orchestration.",
+  "websiteUrl": "https://github.com/ProvarTesting/provardx-cli/blob/main/docs/mcp.md",
+  "icons": [
+    {
+      "src": "https://raw.githubusercontent.com/ProvarTesting/provardx-cli/main/assets/icon.png",
+      "mimeType": "image/png"
+    }
+  ],
   "repository": {
     "url": "https://github.com/ProvarTesting/provardx-cli",
     "source": "github"

From 485e2e4ff3508432fadf8b809be0195fb3a06f7f Mon Sep 17 00:00:00 2001
From: Michael Dailey <49916244+mrdailey99@users.noreply.github.com>
Date: Wed, 22 Apr 2026 16:21:55 -0500
Subject: [PATCH 09/12] Update src/mcp/server.ts

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 src/mcp/server.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index 8520a94a..88adf9c7 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -112,7 +112,7 @@ export function createProvarMcpServer(config: ServerConfig): McpServer {
             {
               uri: 'provar://docs/step-reference',
               mimeType: 'text/markdown',
-              text: '# Provar Test Step Reference\n\nReference doc not found. Run `yarn compile` to build.',
+              text: '# Provar Test Step Reference\n\nReference doc not found. If you are developing from source, rebuild the package. Otherwise, reinstall or upgrade the plugin/package and try again.',
             },
           ],
         };

From 02283ae85767d3e277cdee8b42ce6727a97308c3 Mon Sep 17 00:00:00 2001
From: Michael Dailey <michael.dailey@provartesting.com>
Date: Wed, 22 Apr 2026 16:22:56 -0500
Subject: [PATCH 10/12] PDX-0: feat(mcp): add provar.loop.db prompt and fix DB
 step reference docs

Req: Real-world DB test session exposed 3 root causes: wrong funcCall/variable-path patterns, connectionId using valueClass=string instead of id, and mismatched resultName/dbConnectionName coupling.
Fix: Added provar.loop.db prompt enforcing DB-specific rules; expanded PROVAR_TEST_STEP_REFERENCE.md Database section with critical constraints and correct counter-examples for funcCall and structured paths.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/PROVAR_TEST_STEP_REFERENCE.md  |  97 ++++++++++++++++++++++++-
 docs/mcp.md                         |  23 ++++++
 package.json                        |   2 +-
 scripts/mcp-smoke.cjs               |  10 ++-
 src/mcp/prompts/index.ts            |   2 +
 src/mcp/prompts/loopPrompts.ts      | 103 ++++++++++++++++++++++++++
 src/mcp/tools/qualityHubApiTools.ts |   4 +-
 src/mcp/tools/testCaseGenerate.ts   | 107 ++++++++++++----------------
 test/unit/mcp/loopPrompts.test.ts   |  96 ++++++++++++++++++++++++-
 9 files changed, 372 insertions(+), 72 deletions(-)

diff --git a/docs/PROVAR_TEST_STEP_REFERENCE.md b/docs/PROVAR_TEST_STEP_REFERENCE.md
index eb813c95..0762ad03 100644
--- a/docs/PROVAR_TEST_STEP_REFERENCE.md
+++ b/docs/PROVAR_TEST_STEP_REFERENCE.md
@@ -1125,6 +1125,12 @@ Variable-to-variable or variable-to-literal comparison. For UI field assertions
 
 ## Database Steps
 
+> **Critical constraints — read before generating any Database step XML:**
+>
+> 1. **`connectionId` must use `valueClass="id"`** — not `"string"`. Using `"string"` causes a runtime type error.
+> 2. **`DbConnect.resultName` must exactly equal `SqlQuery.dbConnectionName`** — these two values are the coupling point between the steps. A mismatch causes "connection not found" at runtime.
+> 3. **Never use `{Count(Var)}` or `{Var[0].Field}` string expressions in SetValues/AssertValues** — these are stored verbatim and never evaluated. Use `<value class="funcCall">` for Count and the structured `<value class="variable"><path>` form for indexed field access. See the examples below.
+
 ### DbConnect
 
 ```xml
@@ -1136,12 +1142,14 @@ Variable-to-variable or variable-to-literal comparison. For UI field assertions
       <value class="value" valueClass="string">MyDatabase</value>
     </argument>
     <argument id="connectionId">
-      <value class="value" valueClass="string">database-connection-id</value>
+      <!-- MUST be valueClass="id" — not "string" -->
+      <value class="value" valueClass="id">database-connection-uuid</value>
     </argument>
     <argument id="autoCommit">
       <value class="value" valueClass="boolean">true</value>
     </argument>
     <argument id="resultName">
+      <!-- This value must exactly match dbConnectionName on every SqlQuery that uses this connection -->
       <value class="value" valueClass="string">DbConnection</value>
     </argument>
     <argument id="resultScope">
@@ -1159,10 +1167,11 @@ Variable-to-variable or variable-to-literal comparison. For UI field assertions
          title="SQL Query: DbConnection=&gt;DbResults">
   <arguments>
     <argument id="dbConnectionName">
+      <!-- Must exactly equal the resultName on the DbConnect step above -->
       <value class="value" valueClass="string">DbConnection</value>
     </argument>
     <argument id="query">
-      <value class="value" valueClass="string">SELECT * FROM Users WHERE Status = 'Active'</value>
+      <value class="value" valueClass="string">SELECT Id, Name, Status FROM Users WHERE Status = 'Active'</value>
     </argument>
     <argument id="resultName">
       <value class="value" valueClass="string">DbResults</value>
@@ -1174,6 +1183,90 @@ Variable-to-variable or variable-to-literal comparison. For UI field assertions
 </apiCall>
 ```
 
+### Accessing Database Results — funcCall and structured variable paths
+
+After `SqlQuery`, the result variable (e.g. `DbResults`) is a list of rows. To use the results in `SetValues` or `AssertValues`, you must use structured XML — not `{...}` string expressions.
+
+#### Count the result rows (funcCall)
+
+```xml
+<!-- ✅ CORRECT — funcCall element evaluates at runtime -->
+<argument id="value">
+  <value class="funcCall" id="Count">
+    <argument id="value">
+      <value class="variable">
+        <path element="DbResults"/>
+      </value>
+    </argument>
+  </value>
+</argument>
+
+<!-- ❌ WRONG — string expression stored verbatim, never evaluated -->
+<argument id="value">
+  <value class="value" valueClass="string">{Count(DbResults)}</value>
+</argument>
+```
+
+#### Access a field from a specific row (structured variable path)
+
+```xml
+<!-- ✅ CORRECT — structured path with index filter (0-based) -->
+<argument id="value">
+  <value class="variable">
+    <path element="DbResults">
+      <filter class="index">
+        <index valueClass="decimal">0</index>
+      </filter>
+    </path>
+    <path element="Status"/>
+  </value>
+</argument>
+
+<!-- ❌ WRONG — string expression stored verbatim, never evaluated -->
+<argument id="value">
+  <value class="value" valueClass="string">{DbResults[0].Status}</value>
+</argument>
+```
+
+#### Full SetValues example — extract row count and first-row field
+
+```xml
+<apiCall apiId="com.provar.plugins.bundled.apis.control.SetValues"
+         name="SetValues" testItemId="3"
+         title="Extract DB result values">
+  <arguments>
+    <argument id="values">
+      <value class="list">
+        <!-- Row count into RowCount variable -->
+        <value class="namedValue" name="RowCount">
+          <value class="funcCall" id="Count">
+            <argument id="value">
+              <value class="variable">
+                <path element="DbResults"/>
+              </value>
+            </argument>
+          </value>
+        </value>
+        <!-- First row Status field into FirstStatus variable -->
+        <value class="namedValue" name="FirstStatus">
+          <value class="variable">
+            <path element="DbResults">
+              <filter class="index">
+                <index valueClass="decimal">0</index>
+              </filter>
+            </path>
+            <path element="Status"/>
+          </value>
+        </value>
+      </value>
+    </argument>
+    <argument id="resultScope">
+      <value class="value" valueClass="string">Test</value>
+    </argument>
+  </arguments>
+</apiCall>
+```
+
 ---
 
 ## Web Service Steps
diff --git a/docs/mcp.md b/docs/mcp.md
index 1ba63eea..58006c98 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -67,6 +67,7 @@ The Provar DX CLI ships with a built-in **Model Context Protocol (MCP) server**
     - [provar.loop.fix](#provarloopfix)
     - [provar.loop.review](#provarloopreview)
     - [provar.loop.coverage](#provarloopcoverage)
+    - [provar.loop.db](#provarloopdb)
 - [MCP Resources](#mcp-resources)
   - [provar://docs/step-reference](#provardocsstep-reference)
 - [AI loop pattern](#ai-loop-pattern)
@@ -1685,6 +1686,28 @@ Analyse coverage gaps for a Salesforce object or feature area. Inspects the proj
 
 ---
 
+#### `provar.loop.db`
+
+Generate a Provar XML test case that connects to an **external database** (SQL Server, Oracle, MySQL, PostgreSQL, etc.) and verifies query results. This prompt is distinct from the Salesforce/SOQL loop — it targets `DbConnect` + `SqlQuery` steps and enforces the correct patterns for `funcCall` row counts and structured variable paths for field access, which are the most common source of errors in database test generation.
+
+**Arguments**
+
+| Parameter          | Type   | Required | Description                                                                                                                                                                                        |
+| ------------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `story`            | string | yes      | Description of what the database test should verify. Include the database type, table name, query intent, and what values should be asserted.                                                      |
+| `projectPath`      | string | no       | Absolute path to the Provar project root. Used to locate the `tests/` directory when writing the output file.                                                                                      |
+| `testName`         | string | no       | Optional file name for the test case (without extension). Inferred from the story if omitted.                                                                                                      |
+| `dbConnectionName` | string | no       | The name of the database connection as configured in Provar Connection Manager. Used as the `connectionName` argument on `DbConnect`. If omitted, the story should describe the connection to use. |
+
+**What the prompt enforces:**
+
+- `DbConnect.connectionId` must use `valueClass="id"` — not `"string"`
+- `DbConnect.resultName` must exactly equal `SqlQuery.dbConnectionName` (the coupling point)
+- Row counts use `<value class="funcCall" id="Count">` — not `{Count(Var)}` string expressions
+- Indexed field access uses a structured `<value class="variable"><path><filter class="index">` — not `{Var[0].Field}` string expressions
+
+---
+
 ## MCP Resources
 
 The Provar MCP server also exposes one **MCP resource** — structured reference content that AI clients can read directly from the server.
diff --git a/package.json b/package.json
index 6aeaf3c1..829c2726 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@provartesting/provardx-cli",
   "description": "A plugin for the Salesforce CLI to orchestrate testing activities and report quality metrics to Provar Quality Hub",
-  "version": "1.5.0-beta.8",
+  "version": "1.5.0-beta.9",
   "mcpName": "io.github.provartesting/provar",
   "license": "BSD-3-Clause",
   "plugins": [
diff --git a/scripts/mcp-smoke.cjs b/scripts/mcp-smoke.cjs
index f9eff650..5bdeb5d3 100644
--- a/scripts/mcp-smoke.cjs
+++ b/scripts/mcp-smoke.cjs
@@ -350,6 +350,12 @@ async function runTests() {
     arguments: { objectName: 'Opportunity', projectPath: '/tmp/provar-project' },
   });
 
+  // ── 48. provar.loop.db prompt ─────────────────────────────────────────────
+  await rpc('provar.loop.db (prompt)', 'prompts/get', {
+    name: 'provar.loop.db',
+    arguments: { story: 'Verify Users table has at least one Active record after Salesforce flow runs' },
+  });
+
   server.stdin.end();
 }
 
@@ -358,8 +364,8 @@ async function runTests() {
 // ----------------------------------------------------------------------------
 server.on('close', () => {
   clearTimeout(overallTimer);
-  // initialize + tools/list + 37 tools + prompts/list + 7 prompts/get (setup excluded from default count)
-  const TOTAL_EXPECTED = 47 + (INCLUDE_SETUP ? 1 : 0);
+  // initialize + tools/list + 37 tools + prompts/list + 8 prompts/get (setup excluded from default count)
+  const TOTAL_EXPECTED = 48 + (INCLUDE_SETUP ? 1 : 0);
   let passed = 0;
   let failed = 0;
 
diff --git a/src/mcp/prompts/index.ts b/src/mcp/prompts/index.ts
index 21bdd8e0..494ad3eb 100644
--- a/src/mcp/prompts/index.ts
+++ b/src/mcp/prompts/index.ts
@@ -16,6 +16,7 @@ import {
   registerLoopFixPrompt,
   registerLoopReviewPrompt,
   registerLoopCoveragePrompt,
+  registerLoopDbPrompt,
 } from './loopPrompts.js';
 
 export function registerAllPrompts(server: McpServer): void {
@@ -26,4 +27,5 @@ export function registerAllPrompts(server: McpServer): void {
   registerLoopFixPrompt(server);
   registerLoopReviewPrompt(server);
   registerLoopCoveragePrompt(server);
+  registerLoopDbPrompt(server);
 }
diff --git a/src/mcp/prompts/loopPrompts.ts b/src/mcp/prompts/loopPrompts.ts
index 26702b0e..426a67d9 100644
--- a/src/mcp/prompts/loopPrompts.ts
+++ b/src/mcp/prompts/loopPrompts.ts
@@ -394,3 +394,106 @@ Begin with step 1: list the .testcase files in ${projectPath}/tests/ and search
     })
   );
 }
+
+// ── Prompt: provar.loop.db ────────────────────────────────────────────────────
+
+export function registerLoopDbPrompt(server: McpServer): void {
+  server.prompt(
+    'provar.loop.db',
+    'Generate a Provar XML test case that connects to an external database (SQL Server, Oracle, MySQL, etc.) and verifies query results. Distinct from Salesforce/SOQL flows — this targets DbConnect + SqlQuery steps. Retrieves corpus examples for grounding, enforces correct funcCall/variable-path patterns, generates the test, then validates.',
+    {
+      story: z
+        .string()
+        .describe(
+          'Description of what the database test should verify. Include the database type (e.g. "SQL Server"), table name, query intent, and what values should be asserted (e.g. "Verify that the Users table contains an active user record with Status=Active after a Salesforce flow runs").'
+        ),
+      projectPath: z
+        .string()
+        .optional()
+        .describe('Absolute path to the Provar project root. Used to locate the tests/ directory.'),
+      testName: z
+        .string()
+        .optional()
+        .describe('Optional file name for the test case (without extension). Inferred from the story if omitted.'),
+      dbConnectionName: z
+        .string()
+        .optional()
+        .describe(
+          'The name of the database connection as configured in Provar Connection Manager. Used as the connectionName argument on DbConnect. If omitted, the story should describe it.'
+        ),
+    },
+    ({ story, projectPath, testName, dbConnectionName }) => ({
+      messages: [
+        {
+          role: 'user' as const,
+          content: {
+            type: 'text' as const,
+            text: `You are a Provar test automation expert. Generate a Provar XML test case that validates database state using DbConnect and SqlQuery steps.
+
+This is a **database test**, NOT a Salesforce UI or Apex test. Do not use UiConnect, UiWithScreen, ApexConnect, or ApexCreateObject — use the database step types: DbConnect, SqlQuery, SetValues, AssertValues.
+
+## Workflow
+
+Follow these steps in order:
+
+1. **Get corpus examples** — call \`provar.qualityhub.examples.retrieve\` with a query that includes "database DbConnect SqlQuery" plus keywords from the story (e.g. "database SQL Server verify record count"). Use the returned XML examples as the reference for correct step structure.
+   If the response has \`"count": 0\` with a \`"warning"\` field (API unavailable or not configured), fall back: read the \`provar://docs/step-reference\` MCP resource — specifically the Database Steps section — for the correct attribute schema, then continue.
+
+2. **Generate the test case** — produce valid Provar XML. Apply these database-specific rules:
+
+   **DbConnect rules:**
+   - \`connectionId\` argument MUST use \`valueClass="id"\` — NOT \`"string"\`. Using \`"string"\` causes a runtime type error.
+   - \`resultName\` sets the connection handle name (e.g. \`"DbConnection"\`).
+   - This name must be reused exactly as \`dbConnectionName\` on every SqlQuery step that uses this connection.
+${dbConnectionName ? `   - Use connection name: ${dbConnectionName}` : ''}
+
+   **SqlQuery rules:**
+   - \`dbConnectionName\` must exactly equal the \`resultName\` from the DbConnect step above.
+   - \`resultName\` names the variable that will hold the query result rows (e.g. \`"DbResults"\`).
+
+   **Accessing results in SetValues/AssertValues — critical:**
+   - To count result rows: use \`<value class="funcCall" id="Count">\` — NEVER use \`{Count(Var)}\` string expressions.
+   - To access a field from row N (0-based): use the structured variable path with a \`<filter class="index">\` — NEVER use \`{Var[0].Field}\` string expressions.
+   - String \`{...}\` expressions are stored verbatim and never evaluated. They will always produce wrong results.
+
+   **Pattern for extracting values from results:**
+   \`\`\`xml
+   <!-- Count rows -->
+   <value class="funcCall" id="Count">
+     <argument id="value">
+       <value class="variable"><path element="DbResults"/></value>
+     </argument>
+   </value>
+
+   <!-- Access field from row 0 -->
+   <value class="variable">
+     <path element="DbResults">
+       <filter class="index"><index valueClass="decimal">0</index></filter>
+     </path>
+     <path element="FieldName"/>
+   </value>
+   \`\`\`
+
+3. **Write the file** — save the XML to the tests/ directory in the Provar project.
+   ${projectHint(projectPath)}
+   ${testName ? `Target file name: ${testName}.testcase` : 'Infer the file name from the story (snake_case).'}
+
+4. **Validate** — call \`provar.testcase.validate\` on the saved file. If it reports errors, fix them and re-validate until the file passes clean.
+
+5. **Report** — summarise:
+   - Which query/assertion was implemented
+   - The DbConnect resultName and SqlQuery dbConnectionName used (confirm they match)
+   - Any validation warnings
+   - Any aspects of the story that could not be automated (add \`<!-- TODO: manual verification — <reason> -->\` in the XML)
+
+## Database Test Story
+
+${story}
+
+Begin with step 1: call provar.qualityhub.examples.retrieve with "database DbConnect SqlQuery" plus keywords from the story above.`,
+          },
+        },
+      ],
+    })
+  );
+}
diff --git a/src/mcp/tools/qualityHubApiTools.ts b/src/mcp/tools/qualityHubApiTools.ts
index 130645ec..5e9f2f94 100644
--- a/src/mcp/tools/qualityHubApiTools.ts
+++ b/src/mcp/tools/qualityHubApiTools.ts
@@ -49,8 +49,8 @@ export function registerCorpusExamplesRetrieve(server: McpServer): void {
     'provar.qualityhub.examples.retrieve',
     [
       'Retrieve N similar Provar test case examples from the Quality Hub corpus (1000+ tests in Bedrock KB).',
-      'Use this BEFORE calling provar.testcase.generate to get few-shot grounding examples.',
-      'Pass a user story, requirement, or source test file content as the query.',
+      'Use this BEFORE writing any Provar .testcase XML — whether via provar.testcase.generate, Write, or Edit.',
+      'Pass a user story, requirement, source test file content, or step type keywords as the query.',
       'Returns up to N example Provar XML test cases ordered by similarity score.',
       'If retrieval fails (no auth, network error, rate limit), returns empty examples with a warning — the',
       'generation workflow can still continue without grounding. Never hard-errors on API failure.',
diff --git a/src/mcp/tools/testCaseGenerate.ts b/src/mcp/tools/testCaseGenerate.ts
index a75ce75e..85a9ad80 100644
--- a/src/mcp/tools/testCaseGenerate.ts
+++ b/src/mcp/tools/testCaseGenerate.ts
@@ -22,25 +22,25 @@ import { validateTestCase } from './testCaseValidate.js';
 // and expanded automatically before writing XML.
 
 const SHORTHAND_TO_FQID: Record<string, string> = {
-  UiConnect:          'com.provar.plugins.forcedotcom.core.ui.UiConnect',
-  UiDoAction:         'com.provar.plugins.forcedotcom.core.ui.UiDoAction',
-  UiWithScreen:       'com.provar.plugins.forcedotcom.core.ui.UiWithScreen',
-  UiAssert:           'com.provar.plugins.forcedotcom.core.ui.UiAssert',
-  UiNavigate:         'com.provar.plugins.forcedotcom.core.ui.UiNavigate',
-  UiWithRow:          'com.provar.plugins.forcedotcom.core.ui.UiWithRow',
-  UiScrollToElement:  'com.provar.plugins.forcedotcom.core.ui.UiScrollToElement',
-  ApexConnect:        'com.provar.plugins.forcedotcom.core.testapis.ApexConnect',
-  ApexSoqlQuery:      'com.provar.plugins.forcedotcom.core.testapis.ApexSoqlQuery',
-  ApexCreateObject:   'com.provar.plugins.forcedotcom.core.testapis.ApexCreateObject',
-  ApexReadObject:     'com.provar.plugins.forcedotcom.core.testapis.ApexReadObject',
-  ApexUpdateObject:   'com.provar.plugins.forcedotcom.core.testapis.ApexUpdateObject',
-  ApexDeleteObject:   'com.provar.plugins.forcedotcom.core.testapis.ApexDeleteObject',
-  SetValues:          'com.provar.plugins.bundled.apis.control.SetValues',
-  AssertValues:       'com.provar.plugins.bundled.apis.AssertValues',
-  StepGroup:          'com.provar.plugins.bundled.apis.control.StepGroup',
-  Sleep:              'com.provar.plugins.bundled.apis.control.Sleep',
-  ForEach:            'com.provar.plugins.bundled.apis.control.ForEach',
-  CaseCall:           'com.provar.plugins.bundled.apis.control.CaseCall',
+  UiConnect: 'com.provar.plugins.forcedotcom.core.ui.UiConnect',
+  UiDoAction: 'com.provar.plugins.forcedotcom.core.ui.UiDoAction',
+  UiWithScreen: 'com.provar.plugins.forcedotcom.core.ui.UiWithScreen',
+  UiAssert: 'com.provar.plugins.forcedotcom.core.ui.UiAssert',
+  UiNavigate: 'com.provar.plugins.forcedotcom.core.ui.UiNavigate',
+  UiWithRow: 'com.provar.plugins.forcedotcom.core.ui.UiWithRow',
+  UiScrollToElement: 'com.provar.plugins.forcedotcom.core.ui.UiScrollToElement',
+  ApexConnect: 'com.provar.plugins.forcedotcom.core.testapis.ApexConnect',
+  ApexSoqlQuery: 'com.provar.plugins.forcedotcom.core.testapis.ApexSoqlQuery',
+  ApexCreateObject: 'com.provar.plugins.forcedotcom.core.testapis.ApexCreateObject',
+  ApexReadObject: 'com.provar.plugins.forcedotcom.core.testapis.ApexReadObject',
+  ApexUpdateObject: 'com.provar.plugins.forcedotcom.core.testapis.ApexUpdateObject',
+  ApexDeleteObject: 'com.provar.plugins.forcedotcom.core.testapis.ApexDeleteObject',
+  SetValues: 'com.provar.plugins.bundled.apis.control.SetValues',
+  AssertValues: 'com.provar.plugins.bundled.apis.AssertValues',
+  StepGroup: 'com.provar.plugins.bundled.apis.control.StepGroup',
+  Sleep: 'com.provar.plugins.bundled.apis.control.Sleep',
+  ForEach: 'com.provar.plugins.bundled.apis.control.ForEach',
+  CaseCall: 'com.provar.plugins.bundled.apis.control.CaseCall',
 };
 
 function resolveApiId(apiId: string): string {
@@ -56,16 +56,16 @@ function buildStepWarnings(steps: Array<{ api_id: string }>): string[] {
   if (resolvedIds.includes(SHORTHAND_TO_FQID['ApexReadObject'] ?? '')) {
     warnings.push(
       'ApexReadObject: You must specify field names in the attributes (e.g. fieldList); ' +
-      'if none are provided Provar generates "SELECT  FROM ..." which throws MALFORMED_QUERY. ' +
-      'Prefer ApexSoqlQuery for full control over the SELECT clause and result binding.'
+        'if none are provided Provar generates "SELECT  FROM ..." which throws MALFORMED_QUERY. ' +
+        'Prefer ApexSoqlQuery for full control over the SELECT clause and result binding.'
     );
   }
 
   if (resolvedIds.includes(SHORTHAND_TO_FQID['AssertValues'] ?? '')) {
     warnings.push(
       'AssertValues: Direct index paths like "ResultList[0].FieldName" are NOT supported for ApexSoqlQuery results. ' +
-      'To assert SOQL results use either: (a) a ForEach loop over the result list with AssertValues inside, ' +
-      'or (b) a SetValues step to extract a specific field into a named variable, then assert that variable.'
+        'To assert SOQL results use either: (a) a ForEach loop over the result list with AssertValues inside, ' +
+        'or (b) a SetValues step to extract a specific field into a named variable, then assert that variable.'
     );
   }
 
@@ -79,10 +79,10 @@ const StepSchema = z.object({
     .string()
     .describe(
       'Provar step API ID. Shorthand forms are accepted and auto-expanded to fully-qualified IDs: ' +
-      'UiConnect, UiDoAction, UiWithScreen, UiAssert, UiNavigate, UiWithRow, ' +
-      'ApexConnect, ApexSoqlQuery, ApexCreateObject, ApexReadObject, ApexUpdateObject, ApexDeleteObject, ' +
-      'SetValues, AssertValues, StepGroup, Sleep, ForEach, CaseCall. ' +
-      'Or pass the fully-qualified ID directly (com.provar.plugins.*).'
+        'UiConnect, UiDoAction, UiWithScreen, UiAssert, UiNavigate, UiWithRow, ' +
+        'ApexConnect, ApexSoqlQuery, ApexCreateObject, ApexReadObject, ApexUpdateObject, ApexDeleteObject, ' +
+        'SetValues, AssertValues, StepGroup, Sleep, ForEach, CaseCall. ' +
+        'Or pass the fully-qualified ID directly (com.provar.plugins.*).'
     ),
   name: z.string().describe('Human-readable step name'),
   attributes: z
@@ -90,9 +90,9 @@ const StepSchema = z.object({
     .default({})
     .describe(
       'Step argument values as key/value pairs. Written as <arguments><argument id="key"><value .../></argument></arguments> ' +
-      'inside the <apiCall> element — the format Provar runtime requires. ' +
-      'Do NOT rely on XML attributes on <apiCall>; the runtime silently ignores them. ' +
-      'Example: { "connectionName": "MyOrg", "objectApiName": "Opportunity" }'
+        'inside the <apiCall> element — the format Provar runtime requires. ' +
+        'Do NOT rely on XML attributes on <apiCall>; the runtime silently ignores them. ' +
+        'Example: { "connectionName": "MyOrg", "objectApiName": "Opportunity" }'
     ),
 });
 
@@ -109,6 +109,7 @@ const TOOL_DESCRIPTION = [
   'AssertValues on SOQL results: index paths like "ResultList[0].Field" are not supported.',
   'Use ForEach to iterate the result list, or SetValues to extract a field into a variable first.',
   'Validation: the response always includes a validation field with is_valid, validity_score, quality_score, and any structural issues — check this before attempting to run the test case.',
+  'Grounding: call provar.qualityhub.examples.retrieve before generating to get corpus examples for the scenario — correct XML structure for the step types you need.',
 ].join(' ');
 
 export function registerTestCaseGenerate(server: McpServer, config: ServerConfig): void {
@@ -117,24 +118,12 @@ export function registerTestCaseGenerate(server: McpServer, config: ServerConfig
     TOOL_DESCRIPTION,
     {
       test_case_name: z.string().describe('Test case name (human-readable label)'),
-      test_case_id: z
-        .string()
-        .optional()
-        .describe('Explicit test case id; auto-generated UUID v4 if omitted'),
+      test_case_id: z.string().optional().describe('Explicit test case id; auto-generated UUID v4 if omitted'),
       steps: z.array(StepSchema).default([]).describe('Ordered list of test steps'),
-      output_path: z
-        .string()
-        .optional()
-        .describe('Suggested file path for the .xml file (returned in response)'),
+      output_path: z.string().optional().describe('Suggested file path for the .xml file (returned in response)'),
       overwrite: z.boolean().default(false).describe('Overwrite if output_path file already exists'),
-      dry_run: z
-        .boolean()
-        .default(true)
-        .describe('true = return XML only (default); false = write to output_path'),
-      idempotency_key: z
-        .string()
-        .optional()
-        .describe('Caller-provided key echoed back for deduplication tracking'),
+      dry_run: z.boolean().default(true).describe('true = return XML only (default); false = write to output_path'),
+      idempotency_key: z.string().optional().describe('Caller-provided key echoed back for deduplication tracking'),
     },
     (input) => {
       const requestId = makeRequestId();
@@ -146,9 +135,7 @@ export function registerTestCaseGenerate(server: McpServer, config: ServerConfig
 
       try {
         const xmlContent = buildTestCaseXml(input);
-        const filePath: string | undefined = input.output_path
-          ? path.resolve(input.output_path)
-          : undefined;
+        const filePath: string | undefined = input.output_path ? path.resolve(input.output_path) : undefined;
         let written = false;
 
         if (filePath && !input.dry_run) {
@@ -197,7 +184,7 @@ export function registerTestCaseGenerate(server: McpServer, config: ServerConfig
       } catch (err: unknown) {
         const error = err as Error & { code?: string };
         const errResult = makeError(
-          error instanceof PathPolicyError ? error.code : (error.code ?? 'GENERATE_ERROR'),
+          error instanceof PathPolicyError ? error.code : error.code ?? 'GENERATE_ERROR',
           error.message,
           requestId,
           false
@@ -215,10 +202,11 @@ function buildArgumentsXml(attributes: Record<string, string>): string {
   const entries = Object.entries(attributes);
   if (entries.length === 0) return '';
   const argLines = entries
-    .map(([k, v]) =>
-      `      <argument id="${escapeXmlAttr(k)}">\n` +
-      `        <value class="value" valueClass="String">${escapeXmlContent(v)}</value>\n` +
-      '      </argument>'
+    .map(
+      ([k, v]) =>
+        `      <argument id="${escapeXmlAttr(k)}">\n` +
+        `        <value class="value" valueClass="String">${escapeXmlContent(v)}</value>\n` +
+        '      </argument>'
     )
     .join('\n');
   return `\n      <arguments>\n${argLines}\n      </arguments>\n    `;
@@ -264,16 +252,9 @@ function buildTestCaseXml(input: {
 }
 
 function escapeXmlAttr(value: string): string {
-  return value
-    .replace(/&/g, '&amp;')
-    .replace(/"/g, '&quot;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
+  return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
 
 function escapeXmlContent(value: string): string {
-  return value
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
 }
diff --git a/test/unit/mcp/loopPrompts.test.ts b/test/unit/mcp/loopPrompts.test.ts
index 04edbdc4..35e3a085 100644
--- a/test/unit/mcp/loopPrompts.test.ts
+++ b/test/unit/mcp/loopPrompts.test.ts
@@ -12,6 +12,7 @@ import {
   registerLoopFixPrompt,
   registerLoopReviewPrompt,
   registerLoopCoveragePrompt,
+  registerLoopDbPrompt,
 } from '../../../src/mcp/prompts/loopPrompts.js';
 
 // ── Minimal McpServer mock ─────────────────────────────────────────────────────
@@ -59,11 +60,12 @@ beforeEach(() => {
   registerLoopFixPrompt(server as never);
   registerLoopReviewPrompt(server as never);
   registerLoopCoveragePrompt(server as never);
+  registerLoopDbPrompt(server as never);
 });
 
 describe('loopPrompts — registration', () => {
-  it('registers all 4 loop prompts', () => {
-    assert.equal(server.registrations.length, 4);
+  it('registers all 5 loop prompts', () => {
+    assert.equal(server.registrations.length, 5);
   });
 
   it('registers provar.loop.generate', () => {
@@ -261,3 +263,93 @@ describe('loopPrompts — provar.loop.coverage', () => {
     assert.ok(text.includes('provar.qualityhub.examples.retrieve'), 'should still include corpus retrieval');
   });
 });
+
+describe('loopPrompts — provar.loop.db', () => {
+  it('registers provar.loop.db', () => {
+    const reg = server.registrations.find((r) => r.name === 'provar.loop.db');
+    assert.ok(reg, 'provar.loop.db should be registered');
+    assert.ok(reg.description.toLowerCase().includes('database'), 'description should mention database');
+  });
+
+  it('includes story text in message', () => {
+    const story = 'Verify Users table has Active records after SF flow runs';
+    const result = server.call('provar.loop.db', { story });
+    const text = getMessageText(result);
+    assert.ok(text.includes(story), 'message should contain the story text');
+  });
+
+  it('includes corpus retrieval and validate in workflow', () => {
+    const result = server.call('provar.loop.db', { story: 'any db test' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('provar.qualityhub.examples.retrieve'), 'should reference corpus tool');
+    assert.ok(text.includes('provar.testcase.validate'), 'should reference validator tool');
+  });
+
+  it('references DbConnect and SqlQuery step types', () => {
+    const result = server.call('provar.loop.db', { story: 'any db test' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('DbConnect'), 'should reference DbConnect step type');
+    assert.ok(text.includes('SqlQuery'), 'should reference SqlQuery step type');
+  });
+
+  it('warns about funcCall vs string expressions', () => {
+    const result = server.call('provar.loop.db', { story: 'any db test' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('funcCall'), 'should mention funcCall for count');
+    assert.ok(text.includes('valueClass="id"'), 'should warn about connectionId valueClass="id"');
+  });
+
+  it('warns about resultName / dbConnectionName coupling', () => {
+    const result = server.call('provar.loop.db', { story: 'any db test' });
+    const text = getMessageText(result);
+    assert.ok(
+      text.includes('resultName') && text.includes('dbConnectionName'),
+      'should mention the resultName / dbConnectionName coupling'
+    );
+  });
+
+  it('includes dbConnectionName in message when provided', () => {
+    const result = server.call('provar.loop.db', {
+      story: 'any db test',
+      dbConnectionName: 'MyDB',
+    });
+    const text = getMessageText(result);
+    assert.ok(text.includes('MyDB'), 'message should include provided dbConnectionName');
+  });
+
+  it('includes projectPath when provided', () => {
+    const result = server.call('provar.loop.db', {
+      story: 'any db test',
+      projectPath: '/provar/project',
+    });
+    const text = getMessageText(result);
+    assert.ok(text.includes('/provar/project'), 'message should include project path');
+  });
+
+  it('includes testName when provided', () => {
+    const result = server.call('provar.loop.db', {
+      story: 'any db test',
+      testName: 'VerifyUsersTable',
+    });
+    const text = getMessageText(result);
+    assert.ok(text.includes('VerifyUsersTable'), 'message should include target test name');
+  });
+
+  it('explicitly forbids Salesforce UI and Apex steps', () => {
+    const result = server.call('provar.loop.db', { story: 'any db test' });
+    const text = getMessageText(result);
+    // The prompt names these steps to explicitly forbid them — verify that context
+    assert.ok(
+      text.includes('Do not use') || text.includes('do not use'),
+      'should explicitly forbid Salesforce/Apex steps'
+    );
+    assert.ok(text.includes('UiConnect'), 'should name UiConnect in the forbidden list');
+    assert.ok(text.includes('ApexConnect'), 'should name ApexConnect in the forbidden list');
+  });
+
+  it('includes step-reference fallback instruction', () => {
+    const result = server.call('provar.loop.db', { story: 'any db test' });
+    const text = getMessageText(result);
+    assert.ok(text.includes('provar://docs/step-reference'), 'should include step-reference fallback');
+  });
+});

From 98728f81559efba8ddd66197267a28328d9cb23b Mon Sep 17 00:00:00 2001
From: Michael Dailey <michael.dailey@provartesting.com>
Date: Wed, 22 Apr 2026 16:38:38 -0500
Subject: [PATCH 11/12] PDX-0: fix(mcp): address PR #127 Copilot review
 comments

Req: PR #127 Copilot review flagged two issues: fallback error message uses dev-only yarn compile guidance, and MCP Prompts docs did not clarify client file-access requirements for loop.fix and loop.coverage workflows.
Fix: Updated step-reference fallback text to be meaningful for installed users (reinstall/rebuild), and updated MCP Prompts docs intro to note that file-dependent prompts require a client with local file tools such as Claude Code.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/mcp.md | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/docs/mcp.md b/docs/mcp.md
index 1ba63eea..c74a8d8b 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -291,6 +291,28 @@ After saving, open the **GitHub Copilot Chat** panel and select **Agent** mode.
 >
 > On Windows, you can also try `sf.cmd` as the command.
 
+> **`TypeError: Cannot read properties of undefined (reading 'prototype')` on Windows?**
+> VS Code's MCP server process inherits the _system_ PATH, which may differ from your shell. If you have Node.js 25+ installed at `C:\Program Files\nodejs\` (e.g. from the Windows installer) and use `nvm`/`fnm` for a lower version in your terminal, VS Code will pick Node 25 and crash — see [Prerequisites](#prerequisites).
+>
+> Fix: remove or downgrade the system-wide Node.js to LTS 22, or use the `env` field in `.vscode/mcp.json` to override the PATH:
+>
+> ```json
+> {
+>   "servers": {
+>     "provar": {
+>       "type": "stdio",
+>       "command": "sf",
+>       "args": ["provar", "mcp", "start", "--allowed-paths", "${workspaceFolder}"],
+>       "env": {
+>         "PATH": "C:\\Users\\<you>\\AppData\\Roaming\\fnm\\aliases\\default;${env:PATH}"
+>       }
+>     }
+>   }
+> }
+> ```
+>
+> Replace the `fnm` path with the output of `fnm which 22` (or whichever LTS you use). Run `node --version` from a VS Code terminal to confirm which version it sees.
+
 ### Cursor
 
 Cursor supports project-level and global MCP configuration.
@@ -1566,7 +1588,7 @@ The SF Hosted MCP uses per-user OAuth 2.0, respects field-level security and sha
 
 ## MCP Prompts
 
-The Provar MCP server registers **7 MCP prompts** that pre-wire the tool chain into turnkey workflows. AI clients that support MCP prompts (Claude Desktop, Claude Code) can invoke them directly by name instead of manually orchestrating the underlying tool sequence.
+The Provar MCP server registers **7 MCP prompts** that pre-wire the tool chain into guided workflows. AI clients that support MCP prompts can invoke them directly by name instead of manually orchestrating the underlying tool sequence. **Important:** prompts that need to list, read, or write local project files (for example, `.testcase` files used by `provar.loop.fix` and `provar.loop.coverage`) also require a client with its own workspace/file tools, such as Claude Code or another MCP-compatible client with local file access configured; MCP prompt support alone is not sufficient for those workflows.
 
 ---
 

From 52b9e79c2249aaa6b9a9b74e5e096f1cf2728e30 Mon Sep 17 00:00:00 2001
From: Michael Dailey <michael.dailey@provartesting.com>
Date: Wed, 22 Apr 2026 16:43:17 -0500
Subject: [PATCH 12/12] PDX-0: fix(mcp): address PR review comments on #128
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Req: Two valid Copilot review findings on PR #128 — ambiguous parameter naming and wrong valueClass casing in XML emitter.
Fix: Rename provar.loop.db param dbConnectionName->connectionName to avoid confusion with SqlQuery.dbConnectionName; fix buildArgumentsXml to emit lowercase valueClass="string" instead of "String".

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/mcp.md                            | 12 +++++-----
 src/mcp/prompts/loopPrompts.ts         | 14 ++++++-----
 src/mcp/tools/testCaseGenerate.ts      |  2 +-
 test/unit/mcp/loopPrompts.test.ts      |  6 ++---
 test/unit/mcp/testCaseGenerate.test.ts | 32 ++++++++++++++++++++++----
 5 files changed, 46 insertions(+), 20 deletions(-)

diff --git a/docs/mcp.md b/docs/mcp.md
index 58006c98..3ceca325 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -1692,12 +1692,12 @@ Generate a Provar XML test case that connects to an **external database** (SQL S
 
 **Arguments**
 
-| Parameter          | Type   | Required | Description                                                                                                                                                                                        |
-| ------------------ | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `story`            | string | yes      | Description of what the database test should verify. Include the database type, table name, query intent, and what values should be asserted.                                                      |
-| `projectPath`      | string | no       | Absolute path to the Provar project root. Used to locate the `tests/` directory when writing the output file.                                                                                      |
-| `testName`         | string | no       | Optional file name for the test case (without extension). Inferred from the story if omitted.                                                                                                      |
-| `dbConnectionName` | string | no       | The name of the database connection as configured in Provar Connection Manager. Used as the `connectionName` argument on `DbConnect`. If omitted, the story should describe the connection to use. |
+| Parameter        | Type   | Required | Description                                                                                                                                                                          |
+| ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `story`          | string | yes      | Description of what the database test should verify. Include the database type, table name, query intent, and what values should be asserted.                                        |
+| `projectPath`    | string | no       | Absolute path to the Provar project root. Used to locate the `tests/` directory when writing the output file.                                                                        |
+| `testName`       | string | no       | Optional file name for the test case (without extension). Inferred from the story if omitted.                                                                                        |
+| `connectionName` | string | no       | The Provar Connection Manager database connection name (`DbConnect.connectionName`). Identifies which connection entry to use. If omitted, the story should describe the connection. |
 
 **What the prompt enforces:**
 
diff --git a/src/mcp/prompts/loopPrompts.ts b/src/mcp/prompts/loopPrompts.ts
index 426a67d9..7d74e99b 100644
--- a/src/mcp/prompts/loopPrompts.ts
+++ b/src/mcp/prompts/loopPrompts.ts
@@ -415,14 +415,14 @@ export function registerLoopDbPrompt(server: McpServer): void {
         .string()
         .optional()
         .describe('Optional file name for the test case (without extension). Inferred from the story if omitted.'),
-      dbConnectionName: z
+      connectionName: z
         .string()
         .optional()
         .describe(
-          'The name of the database connection as configured in Provar Connection Manager. Used as the connectionName argument on DbConnect. If omitted, the story should describe it.'
+          'The Provar Connection Manager database connection name (DbConnect.connectionName). This identifies which connection entry to use. If omitted, the story should describe the connection to use.'
         ),
     },
-    ({ story, projectPath, testName, dbConnectionName }) => ({
+    ({ story, projectPath, testName, connectionName }) => ({
       messages: [
         {
           role: 'user' as const,
@@ -442,10 +442,12 @@ Follow these steps in order:
 2. **Generate the test case** — produce valid Provar XML. Apply these database-specific rules:
 
    **DbConnect rules:**
+   - \`connectionName\` argument identifies the Connection Manager entry (e.g. \`"MyDatabase"\`).${
+     connectionName ? `\n   - Use connection name: ${connectionName}` : ''
+   }
    - \`connectionId\` argument MUST use \`valueClass="id"\` — NOT \`"string"\`. Using \`"string"\` causes a runtime type error.
-   - \`resultName\` sets the connection handle name (e.g. \`"DbConnection"\`).
-   - This name must be reused exactly as \`dbConnectionName\` on every SqlQuery step that uses this connection.
-${dbConnectionName ? `   - Use connection name: ${dbConnectionName}` : ''}
+   - \`resultName\` sets the **connection handle** — the variable name used to refer to this open connection (e.g. \`"DbConnection"\`). Choose any valid identifier.
+   - This handle must be reused exactly as \`dbConnectionName\` on every SqlQuery step that uses this connection.
 
    **SqlQuery rules:**
    - \`dbConnectionName\` must exactly equal the \`resultName\` from the DbConnect step above.
diff --git a/src/mcp/tools/testCaseGenerate.ts b/src/mcp/tools/testCaseGenerate.ts
index 85a9ad80..d4ec39fa 100644
--- a/src/mcp/tools/testCaseGenerate.ts
+++ b/src/mcp/tools/testCaseGenerate.ts
@@ -205,7 +205,7 @@ function buildArgumentsXml(attributes: Record<string, string>): string {
     .map(
       ([k, v]) =>
         `      <argument id="${escapeXmlAttr(k)}">\n` +
-        `        <value class="value" valueClass="String">${escapeXmlContent(v)}</value>\n` +
+        `        <value class="value" valueClass="string">${escapeXmlContent(v)}</value>\n` +
         '      </argument>'
     )
     .join('\n');
diff --git a/test/unit/mcp/loopPrompts.test.ts b/test/unit/mcp/loopPrompts.test.ts
index 35e3a085..1c49a270 100644
--- a/test/unit/mcp/loopPrompts.test.ts
+++ b/test/unit/mcp/loopPrompts.test.ts
@@ -308,13 +308,13 @@ describe('loopPrompts — provar.loop.db', () => {
     );
   });
 
-  it('includes dbConnectionName in message when provided', () => {
+  it('includes connectionName in message when provided', () => {
     const result = server.call('provar.loop.db', {
       story: 'any db test',
-      dbConnectionName: 'MyDB',
+      connectionName: 'MyDB',
     });
     const text = getMessageText(result);
-    assert.ok(text.includes('MyDB'), 'message should include provided dbConnectionName');
+    assert.ok(text.includes('MyDB'), 'message should include provided connectionName');
   });
 
   it('includes projectPath when provided', () => {
diff --git a/test/unit/mcp/testCaseGenerate.test.ts b/test/unit/mcp/testCaseGenerate.test.ts
index 188a19b7..cd244445 100644
--- a/test/unit/mcp/testCaseGenerate.test.ts
+++ b/test/unit/mcp/testCaseGenerate.test.ts
@@ -156,9 +156,9 @@ describe('provar.testcase.generate', () => {
       const result = server.call('provar.testcase.generate', {
         test_case_name: 'Multi Step',
         steps: [
-          { api_id: 'UiConnect',  name: 'Connect',  attributes: {} },
+          { api_id: 'UiConnect', name: 'Connect', attributes: {} },
           { api_id: 'UiNavigate', name: 'Navigate', attributes: {} },
-          { api_id: 'UiDoAction', name: 'Click',    attributes: {} },
+          { api_id: 'UiDoAction', name: 'Click', attributes: {} },
         ],
         dry_run: true,
         overwrite: false,
@@ -177,7 +177,7 @@ describe('provar.testcase.generate', () => {
       const result = server.call('provar.testcase.generate', {
         test_case_name: 'Count Test',
         steps: [
-          { api_id: 'UiConnect',  name: 'Step 1', attributes: {} },
+          { api_id: 'UiConnect', name: 'Step 1', attributes: {} },
           { api_id: 'UiNavigate', name: 'Step 2', attributes: {} },
         ],
         dry_run: true,
@@ -202,7 +202,10 @@ describe('provar.testcase.generate', () => {
       assert.equal(typeof validation['validity_score'], 'number');
       assert.equal(typeof validation['quality_score'], 'number');
       assert.equal(validation['is_valid'], true, 'Well-formed generated XML should be valid');
-      assert.ok(!('best_practices_violations' in validation), 'best_practices_violations should be omitted from slim response');
+      assert.ok(
+        !('best_practices_violations' in validation),
+        'best_practices_violations should be omitted from slim response'
+      );
     });
 
     it('emits a TODO comment when no steps are provided', () => {
@@ -368,4 +371,25 @@ describe('provar.testcase.generate', () => {
       assert.equal(parseText(result)['idempotency_key'], 'dedup-key-abc');
     });
   });
+
+  describe('XML argument valueClass casing', () => {
+    it('emits lowercase valueClass="string" not uppercase "String"', () => {
+      const result = server.call('provar.testcase.generate', {
+        test_case_name: 'ValueClass Test',
+        steps: [
+          {
+            api_id: 'UiConnect',
+            name: 'Connect',
+            attributes: { connectionName: 'MyOrg' },
+          },
+        ],
+        dry_run: true,
+        overwrite: false,
+      });
+
+      const xml = parseText(result)['xml_content'] as string;
+      assert.ok(xml.includes('valueClass="string"'), 'Expected lowercase valueClass="string"');
+      assert.ok(!xml.includes('valueClass="String"'), 'Must not emit uppercase valueClass="String"');
+    });
+  });
 });