AX-2162: Document Claude Code install, verify, and recovery

.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "jfrog": {
       "type": "http",
-      "url": "${JFROG_URL}/mcp"
+      "url": "https://${JFROG_PLATFORM_URL}/mcp"
     }
   }
 }

CONTRIBUTING.md

@@ -47,6 +47,7 @@ This downloads the pinned upstream tarball and replaces the contents of `skills/
 - [ ] No secrets, credentials, or files under `**/local-cache/` committed.
 - [ ] If the skill tree changed: `pin` in `.github/scripts/sync-skills-vendor.json` matches the upstream tag the new tree was generated from.
 - [ ] Smoke-test: `claude --plugin-dir .` from the repo root.
+- [ ] README includes a **Verify** section and does not send readers to another plugin repository for install or recovery.
 
 ### Submitting to the Claude plugin directory
 

README.md

@@ -8,7 +8,7 @@ The JFrog plugin provides the following capabilities, grouped by component:
 
 | Component | Feature | Description |
 | --- | --- | --- |
-| **MCP** | JFrog MCP server | Remote JFrog MCP server auto-attached to every session via `.mcp.json` at `${JFROG_URL}/mcp` (OAuth, no API keys). |
+| **MCP** | JFrog MCP server | Remote JFrog MCP server auto-attached to every session via `.mcp.json` at `https://${JFROG_PLATFORM_URL}/mcp` (OAuth, no API keys). |
 | **Skill** | JFrog Platform | Interact with Artifactory repositories, builds, permissions, users, access tokens, projects, release bundles, and platform administration via the JFrog CLI and REST/GraphQL APIs. Also covers security audits, CVE lookups, and Advanced Security exposure queries. |
 | **Skill** | Package safety & download | Check whether npm, Maven, PyPI, Go, and other packages are safe, curated, or allowed, then download them through Artifactory remote caches or curation-aware package managers. |
 | **Hook + Skill** | Agent Package Resolution (Preview) | Automatically route packages installed by the AI agent through your organization's JFrog Artifactory, keeping agent-driven installs inside your Curation, Xray, and governance perimeter. |
@@ -26,7 +26,7 @@ Before installing, make sure you have:
 - **Node.js** (≥ 18) — with `npx` on your `PATH` (used by the Agent Guard).
 - **Skill runtime requirements** — `jf` CLI, `jq`, and `curl` on `PATH`, plus a configured JFrog instance. For the minimum versions, see the upstream skills [`Requirements`](https://github.com/jfrog/jfrog-skills/blob/v0.11.0/README.md#requirements). Configure the CLI with `jf config add` — see [Authentication](#authentication).
 - **JFrog AI Catalog** (optional) — If you want to use the Agent Guard feature, your JFrog subscription needs to include the AI Catalog entitlement. Contact your JFrog account team if you're unsure whether it's enabled.
-- **JFrog CLI ≥ 2.105.0** (optional) — If you want the Agent Guard to auto-resolve credentials/server ID from the JFrog CLI instead of `JFROG_URL`/`JFROG_ACCESS_TOKEN` env vars. Older CLIs don't support the `--format` flag used by `jf config show` for this.
+- **JFrog CLI ≥ 2.105.0** (optional) — If you want the Agent Guard to auto-resolve the credentials/server ID from the JFrog CLI configuration. Older CLIs don't support the `--format` flag used by `jf config show` for this.
 - **JFrog project** (optional) — If you want to use the Agent Guard feature.
 
 ---
@@ -54,6 +54,8 @@ claude plugin marketplace update claude-plugins-official
 claude plugin install jfrog@claude-plugins-official
 ```
 
+Then run **`/jfrog-init`** to complete the shared readiness walk, **restart Claude Code**, and verify below.
+
 ### Local development
 
 From a clone of this repository (repository root **is** the plugin root):
@@ -70,7 +72,7 @@ claude --plugin-dir /path/to/claude-plugin
 
 | Variable | Description |
 | --- | --- |
-| `JFROG_URL` | Your JFrog platform URL, e.g. `https://mycompany.jfrog.io` (no trailing `/`) |
+| `JFROG_PLATFORM_URL` | Your JFrog platform host, e.g. `mycompany.jfrog.io` (no `https://`, no trailing `/`). The MCP URL is `https://${JFROG_PLATFORM_URL}/mcp`. |
 | `JFROG_ACCESS_TOKEN` | Your JFrog access token |
 
 ### 2. Configure the JFrog CLI
@@ -84,6 +86,28 @@ If you have never configured the JFrog CLI on this machine:
    ```
 3. Follow the interactive prompts to enter the same JFrog platform URL and access token.
 
+Setting `JFROG_PLATFORM_URL` / `JFROG_ACCESS_TOKEN` alone does **not** replace a successful `/jfrog-init` walk or repair a failed one. Fix the step `/jfrog-init` reports, re-run it, then restart Claude Code.
+
+---
+
+## Verify
+
+Verification is a required install step, not a troubleshooting fallback:
+
+1. `/plugins` → **Installed** — the JFrog plugin is listed.
+2. Run **`/jfrog-init`** — it completes without blocking errors. Restart Claude Code if it changed the MCP config.
+3. `jf rt ping` — succeeds against your configured server.
+
+If a check fails, see [Recovery](#recovery). Fix the step `/jfrog-init` reports, re-run it, then restart Claude Code.
+
+## Recovery
+
+| Symptom | Do this | Do **not** do this |
+| --- | --- | --- |
+| MCP missing after install | Run `/jfrog-init`, complete OAuth if prompted, **restart Claude Code**, re-check MCP tools. | Assume `JFROG_PLATFORM_URL` alone will register MCP. |
+| `/jfrog-init` stopped at CLI/auth | Follow the skill prompt, then **re-run `/jfrog-init`**. | Skip init and only export env vars. |
+| Install fails with marketplace schema errors | Run `claude plugin marketplace update claude-plugins-official` and retry. | Treat `plugins.0.source` as a diagnosis of this plugin. |
+
 ---
 
 ## Plugin MCP rewrite (Agent Guard)

docs/package-resolution-user-guide.md

@@ -101,12 +101,9 @@ To turn it off in the config file itself, set `"enabled": false`. If your file i
 
 This is a preview, and your feedback directly shapes what ships next. Please tell us about anything that felt confusing, broken, or surprising, good or bad.
 
-File an issue on GitHub, in whichever plugin repo you use:
+File an issue on GitHub: [github.com/jfrog/claude-plugin/issues](https://github.com/jfrog/claude-plugin/issues)
 
-- Cursor: [github.com/jfrog/cursor-plugin/issues](https://github.com/jfrog/cursor-plugin/issues)
-- Claude Code: [github.com/jfrog/claude-plugin/issues](https://github.com/jfrog/claude-plugin/issues)
-- VS Code: [github.com/jfrog/vscode-plugin/issues](https://github.com/jfrog/vscode-plugin/issues)
-- Email: plugins-feedback@jfrog.com
+Email: plugins-feedback@jfrog.com
 
 ---