docs(mcp): add npx alternative and fix Claude Code setup instructions

docs/mcp-pilot-guide.md

@@ -80,7 +80,19 @@ Restart Claude Desktop after saving the file. The Provar tools will appear in th
 
 #### Claude Code (VS Code / CLI)
 
-Add to your project's `.claude/mcp.json`:
+Claude Code can be configured via the `claude` CLI command or by editing a JSON config file. Both work whether you're in the terminal, the VS Code extension, or the Claude Code Desktop app.
+
+**Via terminal (recommended for first-time setup):**
+
+```sh
+# User-scoped — works across all projects
+claude mcp add provar -s user -- sf provar mcp start --allowed-paths /path/to/your/provar/project
+
+# Project-scoped, shared — writes .mcp.json at project root; commit to source control
+claude mcp add provar -s project -- sf provar mcp start --allowed-paths /path/to/your/provar/project
+```
+
+**Via config file** — create `.mcp.json` at your project root:
 
 ```json
 {
@@ -93,10 +105,23 @@ Add to your project's `.claude/mcp.json`:
 }
 ```
 
-Or add directly from the Claude Code session:
+**`sf` not found?** GUI environments often start with a restricted PATH. Use `npx` instead:
 
+```sh
+claude mcp add provar -s user -- npx -y @salesforce/cli provar mcp start --allowed-paths /path/to/your/provar/project
 ```
-/mcp add provar sf provar mcp start --allowed-paths /path/to/project
+
+Or in the config file:
+
+```json
+{
+  "mcpServers": {
+    "provar": {
+      "command": "npx",
+      "args": ["-y", "@salesforce/cli", "provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"]
+    }
+  }
+}
 ```
 
 #### GitHub Copilot (VS Code)
@@ -109,15 +134,15 @@ Create or edit `.vscode/mcp.json` in your workspace root:
     "provar": {
       "type": "stdio",
       "command": "sf",
-      "args": ["provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"]
+      "args": ["provar", "mcp", "start", "--allowed-paths", "${workspaceFolder}"]
     }
   }
 }
 ```
 
 Open the **GitHub Copilot Chat** panel and switch to **Agent** mode. The Provar tools will appear in the tool list.
 
-> **Windows:** Use `sf.cmd` instead of `sf` if VS Code cannot find the command.
+> **`sf` not found?** Use `npx` instead: replace `"command": "sf"` with `"command": "npx"` and prepend `"-y", "@salesforce/cli"` to the `args` array. On Windows, you can also try `sf.cmd`.
 
 #### Cursor
 
@@ -349,14 +374,15 @@ NitroX is Provar's Hybrid Model for locators — it maps Salesforce component-ba
 **Goal:** Demonstrate the full Phase 2 AI-assisted test generation loop: org metadata → corpus retrieval → LLM synthesis → generate + validate.
 
 **Setup:**
+
 1. Run `sf provar auth login` and complete the browser login (Provar API key).
-2. *(Optional but recommended)* Connect the Salesforce Hosted MCP Server alongside Provar MCP. Add `https://api.salesforce.com/platform/mcp/v1/platform/sobject-reads` to your MCP client config and authenticate with OAuth. This gives the AI real field API names for your org.
+2. _(Optional but recommended)_ Connect the Salesforce Hosted MCP Server alongside Provar MCP. Add `https://api.salesforce.com/platform/mcp/v1/platform/sobject-reads` to your MCP client config and authenticate with OAuth. This gives the AI real field API names for your org.
 
 > "I want to generate a Provar test case for: As a sales rep I want to create an Opportunity in Salesforce with a close date, amount, and stage. Check my org's Opportunity schema first, then find similar corpus examples."
 
 **What to look for:**
 
-- *(If SF MCP connected)* `getObjectSchema` called for `Opportunity` — AI uses real field names (e.g. `Amount`, `CloseDate`, `StageName`) in the corpus query
+- _(If SF MCP connected)_ `getObjectSchema` called for `Opportunity` — AI uses real field names (e.g. `Amount`, `CloseDate`, `StageName`) in the corpus query
 - `provar.qualityhub.examples.retrieve` called with the enriched user story as query, returning `examples` array with `similarity_score` values and XML content
 - The AI using the retrieved XML as few-shot context when calling `provar.testcase.generate`
 - `provar.testcase.validate` confirming `quality_score >= 70`

docs/mcp.md

@@ -147,20 +147,26 @@ sf provar mcp start -a /workspace/project-a -a /workspace/project-b
 
 ### Claude Code
 
-The simplest approach is the `claude mcp add` CLI command:
+Claude Code can be configured via the `claude` CLI command or by editing a JSON config file. Both approaches work whether you're using the Claude Code terminal, the VS Code extension, or the Claude Code Desktop app.
+
+#### Via terminal (one-time setup)
+
+Run one of the following in a terminal, choosing your preferred scope:
 
 ```sh
-# User-scoped — works across all your projects
+# User-scoped — registers once and works across all your projects
 claude mcp add provar -s user -- sf provar mcp start --allowed-paths /path/to/your/provar/project
 
-# Project-scoped, shared — creates .mcp.json in project root (commit to source control)
+# Project-scoped, shared — run from your project root; writes .mcp.json there; commit to source control
 claude mcp add provar -s project -- sf provar mcp start --allowed-paths /path/to/your/provar/project
 
-# Project-scoped, private — stored in .claude/settings.local.json (not committed)
+# Project-scoped, private — stored in .claude/settings.local.json; not committed
 claude mcp add provar -s local -- sf provar mcp start --allowed-paths /path/to/your/provar/project
 ```
 
-You can also edit `.mcp.json` at your project root directly for the shared project config:
+#### Via config file (manual / VS Code)
+
+Create or edit `.mcp.json` at your project root for project-scoped configuration shared with your team:
 
 ```json
 {
@@ -173,9 +179,36 @@ You can also edit `.mcp.json` at your project root directly for the shared proje
 }
 ```
 
+For user-scoped (global) configuration that applies across all projects, add the same `provar` entry under `mcpServers` in `~/.claude.json`.
+
+#### `sf` not found? Use `npx`
+
+GUI environments (VS Code, Claude Code Desktop, Claude Desktop) often start with a restricted PATH that doesn't include the `sf` binary. Using `npx` as the command resolves this — it finds `@salesforce/cli` from your npm cache without requiring `sf` to be on PATH.
+
+**Via terminal:**
+
+```sh
+claude mcp add provar -s user -- npx -y @salesforce/cli provar mcp start --allowed-paths /path/to/your/provar/project
+```
+
+**Via config file:**
+
+```json
+{
+  "mcpServers": {
+    "provar": {
+      "command": "npx",
+      "args": ["-y", "@salesforce/cli", "provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"]
+    }
+  }
+}
+```
+
+> The Provar plugin must still be installed first via `sf plugins install @provartesting/provardx-cli@beta`. The npx invocation shares the same plugin directory as the globally installed `sf` binary.
+
 ### Claude Desktop
 
-Add a `provar` entry to your Claude Desktop MCP configuration file.
+Edit the Claude Desktop MCP configuration file. Open it via **Claude menu → Settings → Developer → Edit Config**, or navigate to it directly:
 
 - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
 - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
@@ -191,9 +224,22 @@ Add a `provar` entry to your Claude Desktop MCP configuration file.
 }
 ```
 
-> **Windows:** If `sf` is not found, use `sf.cmd` as the command. Claude Desktop may not inherit the full shell PATH, so `sf.cmd` (the npm-installed wrapper) is more reliable.
-
-Restart Claude Desktop after saving the file. The Provar tools will appear in the tool list.
+Fully quit and relaunch Claude Desktop after saving (Cmd+Q on macOS, not just close the window). The Provar tools will appear in the tool list.
+
+> **`sf` not found?** Claude Desktop launches with a restricted PATH on macOS and Windows. If the server fails to start, use `npx` instead:
+>
+> ```json
+> {
+>   "mcpServers": {
+>     "provar": {
+>       "command": "npx",
+>       "args": ["-y", "@salesforce/cli", "provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"]
+>     }
+>   }
+> }
+> ```
+>
+> On Windows, you may also try `sf.cmd` as the command if npx is not available.
 
 ### GitHub Copilot (VS Code)
 
@@ -205,15 +251,29 @@ Create or edit `.vscode/mcp.json` in your workspace root (commit this to source
     "provar": {
       "type": "stdio",
       "command": "sf",
-      "args": ["provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"]
+      "args": ["provar", "mcp", "start", "--allowed-paths", "${workspaceFolder}"]
     }
   }
 }
 ```
 
-> **Windows:** Use `sf.cmd` instead of `sf` if VS Code cannot find the command.
-
-After saving, open the **GitHub Copilot Chat** panel and select **Agent** mode. The Provar tools will be listed in the available tools.
+After saving, open the **GitHub Copilot Chat** panel and select **Agent** mode. The Provar tools will appear in the available tools.
+
+> **`sf` not found?** VS Code may not inherit your shell PATH. Use `npx` instead:
+>
+> ```json
+> {
+>   "servers": {
+>     "provar": {
+>       "type": "stdio",
+>       "command": "npx",
+>       "args": ["-y", "@salesforce/cli", "provar", "mcp", "start", "--allowed-paths", "${workspaceFolder}"]
+>     }
+>   }
+> }
+> ```
+>
+> On Windows, you can also try `sf.cmd` as the command.
 
 ### Cursor
 
@@ -247,7 +307,20 @@ Cursor supports project-level and global MCP configuration.
 
 After saving, restart Cursor. The Provar tools will appear under **Settings → MCP**.
 
-> **Windows:** Use `sf.cmd` instead of `sf` if Cursor cannot locate the command.
+> **`sf` not found?** Use `npx` as the command instead:
+>
+> ```json
+> {
+>   "mcpServers": {
+>     "provar": {
+>       "command": "npx",
+>       "args": ["-y", "@salesforce/cli", "provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"]
+>     }
+>   }
+> }
+> ```
+>
+> On Windows, you can also try `sf.cmd` if `npx` is unavailable.
 
 ### Agentforce Vibes
 
@@ -1464,10 +1537,10 @@ Each element in `examples`:
 
 Provar MCP does not include a built-in org introspection tool. Instead, connect the **Salesforce Hosted MCP Server** (`platform/sobject-reads`) alongside Provar MCP and call `getObjectSchema` to retrieve sObject field metadata. Pass the result as additional context in your `provar.qualityhub.examples.retrieve` query.
 
-| Endpoint | URL |
-| -------- | --- |
-| Production | `https://api.salesforce.com/platform/mcp/v1/platform/sobject-reads` |
-| Sandbox | `https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-reads` |
+| Endpoint   | URL                                                                         |
+| ---------- | --------------------------------------------------------------------------- |
+| Production | `https://api.salesforce.com/platform/mcp/v1/platform/sobject-reads`         |
+| Sandbox    | `https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-reads` |
 
 The SF Hosted MCP uses per-user OAuth 2.0, respects field-level security and sharing rules automatically, and is maintained by Salesforce. See [Salesforce Hosted MCP Server docs](https://developer.salesforce.com/docs/platform/hosted-mcp-servers/guide/sobject-reads.html) for setup.
 

docs/provar-mcp-public-docs.md

@@ -97,7 +97,19 @@ Restart Claude Desktop after saving. The Provar tools will appear in the tool li
 
 #### Claude Code (VS Code / CLI)
 
-Add to your project's `.claude/mcp.json`:
+Claude Code can be configured via the `claude` CLI command or by editing a JSON config file. Both approaches work in the terminal, the VS Code extension, and the Claude Code Desktop app.
+
+**Via terminal (recommended):**
+
+```sh
+# User-scoped — works across all your projects
+claude mcp add provar -s user -- sf provar mcp start --allowed-paths /path/to/your/provar/project
+
+# Project-scoped, shared — creates .mcp.json at project root; commit to source control
+claude mcp add provar -s project -- sf provar mcp start --allowed-paths /path/to/your/provar/project
+```
+
+**Via config file** — create `.mcp.json` at your project root:
 
 ```json
 {
@@ -110,26 +122,64 @@ Add to your project's `.claude/mcp.json`:
 }
 ```
 
-Or add directly from a Claude Code session:
+**`sf` not found?** GUI environments (VS Code, Claude Code Desktop) often launch with a restricted PATH that doesn't include `sf`. Use `npx` as the command instead:
+
+```sh
+# Terminal
+claude mcp add provar -s user -- npx -y @salesforce/cli provar mcp start --allowed-paths /path/to/your/provar/project
+```
 
+```json
+{
+  "mcpServers": {
+    "provar": {
+      "command": "npx",
+      "args": ["-y", "@salesforce/cli", "provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"]
+    }
+  }
+}
 ```
-/mcp add provar sf provar mcp start --allowed-paths /path/to/project
+
+#### GitHub Copilot (VS Code)
+
+Create `.vscode/mcp.json` in your workspace root (commit to share with your team):
+
+```json
+{
+  "servers": {
+    "provar": {
+      "type": "stdio",
+      "command": "sf",
+      "args": ["provar", "mcp", "start", "--allowed-paths", "${workspaceFolder}"]
+    }
+  }
+}
 ```
 
+Open the **GitHub Copilot Chat** panel and switch to **Agent** mode. The Provar tools will appear in the tool list.
+
+> **`sf` not found?** Replace `"command": "sf"` with `"command": "npx"` and prepend `"-y", "@salesforce/cli"` to the `args` array.
+
 #### Cursor
 
-In Cursor Settings → MCP, add:
+Add to `.cursor/mcp.json` in your workspace root (project-level) or `~/.cursor/mcp.json` (global):
 
 ```json
 {
-  "provar": {
-    "command": "sf",
-    "args": ["provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"]
+  "mcpServers": {
+    "provar": {
+      "command": "sf",
+      "args": ["provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"]
+    }
   }
 }
 ```
 
-> **Important:** Set `--allowed-paths` to the root of your Provar Automation project directory. This is the folder containing your `.testproject` file. The server will only read and write files within this boundary.
+Restart Cursor after saving. The Provar tools will appear under **Settings → MCP**.
+
+> **`sf` not found?** Replace `"command": "sf"` with `"command": "npx"` and prepend `"-y", "@salesforce/cli"` to the `args` array.
+
+> **Important:** Set `--allowed-paths` to the root of your Provar Automation project directory (the folder containing your `.testproject` file). The server will only read and write files within this boundary.
 
 ---
 
@@ -364,12 +414,14 @@ Open Provar Automation IDE → Help → Manage License → ensure the license is
 The server started successfully but the license cache is over 2 hours old. This is a warning only. If the cache exceeds 48 hours without a successful online re-validation, the next startup will fail. Restart the server while Provar Automation IDE is connected to the internet to refresh the cache.
 
 **`SF_NOT_FOUND` error from Quality Hub / Automation tools**
-The `sf` CLI binary is not on the PATH that the MCP server sees (common with macOS GUI apps). Use the full binary path in your MCP config:
+The `sf` CLI binary is not on the PATH that the MCP server sees (common with macOS and Windows GUI apps). Use `npx` as the command in your MCP config — it resolves `@salesforce/cli` from your npm cache without needing `sf` on PATH:
 
 ```json
-{ "command": "/usr/local/bin/sf", "args": ["provar", "mcp", "start", "--allowed-paths", "..."] }
+{ "command": "npx", "args": ["-y", "@salesforce/cli", "provar", "mcp", "start", "--allowed-paths", "..."] }
 ```
 
+Alternatively, use the full path to the `sf` binary (e.g. `/usr/local/bin/sf` on macOS).
+
 **`PATH_NOT_ALLOWED` error**
 The path passed to a tool is outside the `--allowed-paths` root. Update `--allowed-paths` in your client config and restart the server.