onlycastle · onlycastle · Mar 27, 2026 · Mar 27, 2026 · Mar 27, 2026 · Mar 27, 2026
diff --git a/README.md b/README.md
@@ -37,15 +37,23 @@ In Claude Code:
 
 That's it. The MCP server, analysis skills, and post-session hooks are registered automatically.
 
-### 2. First-time setup
+### 2. Reload plugins
+
+After installing, reload plugins so Claude Code picks up the new MCP server and skills:
+
+```
+/reload-plugins
+```
+
+### 3. First-time setup
 
 On your first Claude Code session after installation, the `bp setup` wizard runs automatically. It verifies your installation, optionally adds a command reference to your CLAUDE.md, and points you toward your first analysis. You can also invoke it manually anytime:
 
 ```
 bp setup
 ```
 
-### 3. Run your analysis
+### 4. Run your analysis
 
 In any Claude Code session, run:
 
@@ -83,7 +91,7 @@ This checks all 8 components (build artifacts, native dependencies, MCP config,
 | Problem | Fix |
 |---------|-----|
 | `better-sqlite3` won't compile | Install build tools: `xcode-select --install` (macOS) or `sudo apt install build-essential python3` (Linux) |
-| MCP server not starting | Restart Claude Code after plugin install |
+| MCP server not starting | Run `/reload-plugins` in Claude Code, or restart Claude Code |
 | Rate limits during analysis | Reduce scope: select fewer projects in `bp setup`, or run analysis during off-peak hours |
 
 ### Uninstalling

diff --git a/docs/agent/PLUGIN.md b/docs/agent/PLUGIN.md
@@ -57,7 +57,7 @@ Claude Code plugin at `packages/plugin/`. MCP server + queued auto-analysis hook
 | `lib/native-deps.ts` | Shared `ensureNativeDeps({ pluginRoot?, fatal? })` — installs better-sqlite3 to pluginRoot/node_modules/ for natural Node resolution |
 | `hooks/session-start-handler.ts` | `SessionStart` hook, first-run detection + queued `bp analyze` context |
 | `hooks/hooks.json` | Hook registration (`SessionStart` + `SessionEnd`) |
-| `skills/bp-setup/SKILL.md` | Guided onboarding wizard skill (7 integer steps, includes project selection) |
+| `skills/bp-setup/SKILL.md` | Guided onboarding wizard skill (MCP Readiness Gate + 7 integer steps, includes project selection) |
 | `skills/bp-analyze/SKILL.md` | Full analysis pipeline orchestrator skill |
 | `.claude-plugin/plugin.json` | Plugin metadata + config schema |
 | `.mcp.json` | MCP server config (stdio transport) |

diff --git a/docs/agent/TROUBLESHOOTING.md b/docs/agent/TROUBLESHOOTING.md
@@ -4,6 +4,10 @@
 
 Analysis runs locally via the Claude Code plugin (`packages/plugin/`). Finished results sync to the server via `POST /api/analysis/sync`. The server no longer runs its own analysis pipeline.
 
+## Plugin Setup (bp-setup)
+
+The `bp-setup` wizard includes an MCP Readiness Gate that retries `get_user_prefs` up to 3 times (0s, 3s, 5s backoff) before proceeding. This handles the delay between plugin install/`/reload-plugins` and the MCP server becoming available. If all 3 attempts fail, the wizard exits with a reinstall suggestion. If the gate passes but `scan_sessions` fails in Step 2, setup continues (non-critical) — project selection in Step 3 will retry or offer defaults.
+
 ## Key Files
 
 | File | Role |

diff --git a/packages/plugin/skills/bp-setup/SKILL.md b/packages/plugin/skills/bp-setup/SKILL.md
@@ -10,16 +10,45 @@ model: opus
 
 You are the **BetterPrompt onboarding assistant**. You guide first-time users through a quick setup that verifies their installation, lets them choose which projects to analyze, optionally integrates a command reference into their project CLAUDE.md, and points them toward their first analysis. The entire process takes about 1 minute.
 
+## MCP Readiness Gate
+
+The BetterPrompt MCP server may still be starting, especially after first install or `/reload-plugins`. Before proceeding, confirm that MCP tools are available.
+
+1. Attempt to call `get_user_prefs`. If it succeeds, proceed to the Pre-Check (reuse the result there).
+2. If the tool call fails because the tool is **not found or not available** (not a tool execution error):
+   a. Print: `"[bp] MCP tools are still loading (this is normal on first run)..."`
+   b. Wait 3 seconds using Bash: `sleep 3`
+   c. Retry `get_user_prefs`.
+3. If the second attempt also fails with tool-not-found:
+   a. Print: `"[bp] Still waiting for MCP server..."`
+   b. Wait 5 seconds using Bash: `sleep 5`
+   c. Retry `get_user_prefs` one final time.
+4. If all 3 attempts fail:
+   - Print:
+     ```
+     [bp] Could not reach BetterPrompt MCP tools after 3 attempts.
+
+     This usually means the plugin was not installed correctly.
+     Try reinstalling: /plugin install betterprompt@betterprompt
+
+     If the problem persists, check ~/.betterprompt/debug.log for details.
+     ```
+   - Do NOT continue with the remaining wizard steps. Exit gracefully.
+5. If the tool call succeeds at any attempt, print: `"[bp] MCP server ready."` and proceed.
+
+**Important**: If the tool **is found** but returns an error result (e.g., a JSON response with an `error` field), that is NOT a readiness issue -- that is a tool execution error. Do not retry in that case; proceed to the Pre-Check and let it handle the error normally.
+
 ## Pre-Check
 
 Before starting the wizard:
 
-1. Call `get_user_prefs` and check `prefs.welcomeCompleted`.
-2. If `welcomeCompleted` is already set **and** the user did NOT pass `--force`:
+1. Reuse the `get_user_prefs` result from the MCP Readiness Gate above.
+2. Check `prefs.welcomeCompleted`.
+3. If `welcomeCompleted` is already set **and** the user did NOT pass `--force`:
    - Tell the user setup was already completed on that date.
    - Ask: **"Re-run setup?"** / **"Skip"**
    - If they choose Skip, exit gracefully.
-3. If `welcomeCompleted` is not set, or `--force` was passed, proceed to Step 1.
+4. If `welcomeCompleted` is not set, or `--force` was passed, proceed to Step 1.
 
 ### Explicit Instruction Shortcut
 
@@ -55,18 +84,20 @@ This setup takes about 1 minute.
 
 ### Step 2: Verify Environment
 
-Call the `scan_sessions` MCP tool to verify the plugin is working (native deps + MCP connection in one shot).
+Call the `scan_sessions` MCP tool to verify the plugin can read session data.
 
 - **On success**: Report what was found:
   - Number of sessions discovered
   - Date range of sessions
   - Sources detected (Claude Code, etc.)
   - List of projects with session counts
-- **On failure**: Report the error clearly and suggest the user verify the plugin is installed correctly (`/plugin install betterprompt@betterprompt`). Do not attempt to register via `claude mcp add`.
+- **On failure**: Since MCP connectivity was already confirmed by the Readiness Gate, a failure here means `scan_sessions` encountered an error reading session data (no sessions found, permission issue, etc.). Report the error but continue with setup -- Step 2 failure is non-critical. The user can still configure preferences and run analysis later.
 
 ### Step 3: Select Projects
 
-Display the project list from Step 2 (name + session count) and let the user choose which projects to include in analysis.
+If Step 2 succeeded, display the project list from Step 2 (name + session count) and let the user choose which projects to include in analysis.
+
+If Step 2 failed (no `scan_sessions` data available), call `scan_sessions` again here. If it still fails, tell the user that project discovery is unavailable and offer two options: **"Analyze all projects"** (sets `selectedProjects: []`) or **"Skip project selection"** (keeps existing selection or sets `selectedProjects: []`). Then proceed to Step 4.
 
 If the user's initial prompt already names the projects to include, do **not** call `AskUserQuestion` for this step. Match the requested names against `scan_sessions.allProjects[].name`, confirm the matched canonical names, and persist them directly.
 
@@ -205,6 +236,7 @@ Use `AskUserQuestion` with these options:
 ## Progress Reporting
 
 Print a brief `[bp]` status line before each step:
+0. `"[bp] Connecting to MCP server..."` (only shown if readiness gate needs to retry)
 1. `"[bp] Step 1: Welcome"`
 2. `"[bp] Step 2: Verifying environment..."`
 3. `"[bp] Step 3: Project selection"`
@@ -215,8 +247,8 @@ Print a brief `[bp]` status line before each step:
 
 ## Important Notes
 
-- Never skip Step 2 (verification) -- it confirms the plugin works.
+- Always run Step 2 (verification), but its failure is non-critical -- MCP connectivity is already confirmed by the Readiness Gate.
 - Always write `welcomeCompleted` at the end, even if the user skipped optional steps.
 - Always use `save_user_prefs` for setup preference updates when available instead of direct file writes.
-- If any step fails, log the error but continue to the next step. Do not abort the entire wizard for a non-critical failure (Steps 4, 5 are non-critical).
+- If any step fails, log the error but continue to the next step. Do not abort the entire wizard for a non-critical failure (Steps 2, 4, 5 are non-critical).
 - The CLAUDE.md block uses HTML comment markers (`<!-- bp:START -->` / `<!-- bp:END -->`) so it can be cleanly replaced or removed later.