feat(plugin): single-session install + setup flow

docs/agent/PLUGIN.md

@@ -51,7 +51,7 @@ Claude Code plugin at `packages/plugin/`. MCP server + queued auto-analysis hook
 | `lib/native-deps.ts` | Shared `ensureNativeDeps()` — idempotent better-sqlite3 installer used by both server-entry and SessionStart hook |
 | `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 |
+| `skills/bp-setup/SKILL.md` | Guided onboarding wizard skill (includes mid-session MCP registration via `claude mcp add`) |
 | `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) |
@@ -146,6 +146,16 @@ Evaluated in order by `shouldTriggerAnalysis(sessionDurationMs)`:
 
 Session count: scans `~/.claude/projects/*/` for `.jsonl` files (filesystem only, no content reading).
 
+## Single-Session Install Flow
+
+After `claude plugin install`, the MCP server isn't running yet (plugin lifecycle starts next session). The `/bp-setup` skill handles this with Step 0.5:
+
+```
+install plugin → /bp-setup → Step 0.5: `claude mcp add -s user -e NODE_PATH=... -e CLAUDE_PLUGIN_DATA=... betterprompt -- node <server-entry.js>` → MCP tools available → continue setup
+```
+
+The `claude mcp add` command registers the server at user scope with `NODE_PATH` and `CLAUDE_PLUGIN_DATA` env vars pointing to `~/.betterprompt/`. On subsequent sessions, the plugin's `.mcp.json` handles server startup normally — Claude Code deduplicates by server name, so the user-scoped entry and the plugin-managed `.mcp.json` entry do not conflict.
+
 ## Queued Auto-Analysis Flow
 
 ```

packages/plugin/.claude-plugin/plugin.json

@@ -7,6 +7,8 @@
     "name": "BetterPrompt"
   },
   "repository": "https://github.com/onlycastle/BetterPrompt",
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
   "configuration": {
     "serverUrl": {
       "type": "string",

packages/plugin/lib/native-deps.ts

@@ -10,10 +10,10 @@
 import { existsSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { join } from 'node:path';
+import { homedir } from 'node:os';
 
 export function ensureNativeDeps(opts?: { fatal?: boolean }): void {
-  const pluginDataDir = process.env.CLAUDE_PLUGIN_DATA;
-  if (!pluginDataDir) return;
+  const pluginDataDir = process.env.CLAUDE_PLUGIN_DATA || join(homedir(), '.betterprompt');
 
   const marker = join(pluginDataDir, 'node_modules', 'better-sqlite3', 'build', 'Release', 'better_sqlite3.node');
   if (existsSync(marker)) return;

packages/plugin/skills/bp-setup/SKILL.md

@@ -37,6 +37,29 @@ your machine.
 This setup takes about 1 minute.
 ```
 
+### Step 0.5: Ensure MCP Server
+
+After a fresh plugin installation, the MCP server is not running yet in the current session. This step registers it so all BetterPrompt tools become available immediately.
+
+1. Run `claude mcp list` via Bash and check whether `betterprompt` appears in the output.
+2. If `betterprompt` is already listed, skip to Step 1.
+3. If NOT listed:
+   a. Find the plugin's server entry point — search for the file matching this glob pattern:
+      ```
+      ~/.claude/plugins/cache/betterprompt/betterprompt/*/dist/mcp/server-entry.js
+      ```
+   b. Create the data directory if it doesn't exist: `mkdir -p ~/.betterprompt`
+   c. Register the MCP server:
+      ```bash
+      claude mcp add -s user \
+        -e NODE_PATH="$HOME/.betterprompt/node_modules" \
+        -e CLAUDE_PLUGIN_DATA="$HOME/.betterprompt" \
+        betterprompt -- \
+        node "<absolute-path-from-step-a>"
+      ```
+   d. Tell the user: "MCP server registered. BetterPrompt tools are now available."
+4. If the server entry point cannot be found, inform the user and suggest reinstalling the plugin.
+
 ### Step 1: Verify Installation
 
 Call the `scan_sessions` MCP tool to confirm the plugin is working.
@@ -147,7 +170,8 @@ Use `AskUserQuestion` with these options:
 
 ## Important Notes
 
-- Never skip Step 1 (verification) -- this confirms the plugin works.
+- Never skip Step 0.5 (MCP server) or Step 1 (verification) -- these confirm the plugin works.
+- Step 0.5 makes install-then-setup possible in a single Claude Code session.
 - Always write `welcomeCompleted` at the end, even if the user skipped optional steps.
 - 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, 3 are non-critical).
 - The CLAUDE.md block uses HTML comment markers (`<!-- bp:START -->` / `<!-- bp:END -->`) so it can be cleanly replaced or removed later.