diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 55111fb..2a7cc3b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -13,8 +13,8 @@ All contributors must sign the [JFrog CLA](https://jfrog.com/cla/) before contri
 3. **Validate** locally:
 
 ```bash
-npm test         # unit tests for the manifest/skill validator
-npm run validate # lint the plugin manifests + skill frontmatter
+npm test                              # unit tests for the manifest/skill validator
+npm run validate                      # lint the plugin manifests + skill frontmatter
 ```
 
 1. **Test** by loading your clone as the plugin. The repo root is the marketplace root (`.agents/plugins/marketplace.json` registers the `jfrog` plugin):
@@ -42,6 +42,7 @@ This downloads the pinned upstream tarball and replaces the contents of `skills/
 ## Pre-release checklist
 
 - [ ] `npm test` and `npm run validate` pass.
+- [ ] README includes **Verify** and **Recovery** and does not send readers to another plugin repository for those steps.
 - [ ] `version` bumped and **identical** in both [`.codex-plugin/plugin.json`](.codex-plugin/plugin.json) and [`package.json`](package.json) (CI enforces the match).
 - [ ] No secrets, credentials, or API keys committed.
 - [ ] If the skill tree changed: `pin` in [`scripts/sync-skills-vendor.json`](scripts/sync-skills-vendor.json) matches the upstream tag the new tree was generated from, and the README Prerequisites link points at that tag.
diff --git a/README.md b/README.md
index 5bf79a9..c2531f1 100644
--- a/README.md
+++ b/README.md
@@ -90,6 +90,32 @@ Restart Codex; the `jfrog` MCP server and its tools are now available (verify wi
 
 ---
 
+## Verify
+
+Verification is a required install step, not a troubleshooting fallback. After
+restarting Codex, confirm all four:
+
+1. `codex plugin list` — `jfrog@codex-plugin` is installed and enabled.
+2. `/plugins` in the Codex TUI — the JFrog plugin lists its skills (`jfrog` and others).
+3. `codex mcp list` — `jfrog` is connected (after `codex mcp login jfrog`).
+4. `jf rt ping` — succeeds against your configured JFrog server.
+
+If any check fails, see [Recovery](#recovery). Setting MCP environment variables
+by hand does not repair a failed initialization — re-run `jfrog-init` instead.
+
+---
+
+## Recovery
+
+| Symptom | Do this | Do **not** do this |
+| --- | --- | --- |
+| MCP missing after install | Run `jfrog-init`, edit the plugin `.mcp.json` host if needed, run `codex mcp login jfrog`, **restart Codex**, then `codex mcp list`. | Assume exporting `JFROG_PLATFORM_URL` will register MCP. Codex reads the host from `.mcp.json`. |
+| `jfrog-init` stopped at CLI/auth | Follow the skill prompt (`jf config add`, web login, or token path), then **re-run `jfrog-init`**. | Skip init and only export env vars. |
+| Placeholder still in `.mcp.json` | Set the host in `<install-path>/.mcp.json`, run `codex mcp login jfrog`, restart Codex. | Reinstall the plugin when only the host placeholder is wrong. |
+| Plugin not listed | Re-run `codex plugin add jfrog@codex-plugin` from a regular terminal, then restart Codex. | Run install commands from inside the Codex TUI. |
+
+---
+
 ## Usage
 
 Once configured, interact with the JFrog plugin through natural language.