feat(plugin): first-run onboarding + sequential Phase 2 execution (#172)

* fix(plugin): run Phase 2 skills sequentially to eliminate rate limits

Two-batch approach (3+4) still triggered rate limit failures on Claude
Max. Switch to fully sequential execution — each of the 7 Phase 2 skills
runs one at a time with the previous completing before the next starts.

Adds ~5 min to pipeline wall time but eliminates all concurrent Sonnet
burst issues.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(plugin): add user preferences module

Persistent prefs stored in ~/.betterprompt/prefs.json, separate from
the transient plugin-state.json.  Provides readPrefs/writePrefs (merge
semantics) and isFirstRun() for onboarding detection.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(plugin): add first-run onboarding skill

/bp-setup wizard: verifies installation via scan_sessions, optionally
adds command reference to CLAUDE.md, one-time GitHub star prompt, and
points users toward their first /bp-analyze run.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat(plugin): integrate first-run detection into session hooks

SessionStart hook now checks isFirstRun() before pending-analysis,
injecting /bp-setup context for new users.  Priority order: skip
compact → first-run → pending analysis → no-op.  DI via deps object
keeps the handler fully testable.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore(plugin): rebuild dist with onboarding changes

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add first-run onboarding to plugin docs and README

README: rewrite install flow with terminal commands, add /bp-setup step.
PLUGIN.md: register prefs.ts, bp-setup skill, session-start priority.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: fix stale "2 batches" header in LLM_FLOW.md Phase 2 section

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add prefs.json cleanup step to plugin testing checklist

Without this step, a leftover welcomeCompleted flag silently skips the
first-run onboarding flow during testing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: onlycastle

CLAUDE.md

@@ -116,7 +116,8 @@ See `docs/agent/DEPLOYMENT.md` for the current self-hosted runtime model and def
 > 5. Delete `~/.claude/plugins/marketplaces/betterprompt/`
 > 6. Clear any project-level `settings.local.json` with betterprompt entries
 > 7. Check for and remove any plugin state databases (`bp-results*`, `bp-stage*`)
-> 8. Validate all JSON files after edits (trailing comma issues are common)
+> 8. Delete `~/.betterprompt/prefs.json` to reset first-run onboarding state
+> 9. Validate all JSON files after edits (trailing comma issues are common)
 
 ## Documentation
 

README.md

@@ -29,18 +29,24 @@ The recommended way to use BetterPrompt. Zero configuration required.
 
 ### 1. Install the plugin
 
-In any Claude Code session, run:
+In your terminal:
 
-```
-/plugin marketplace add onlycastle/BetterPrompt
-/plugin install betterprompt@betterprompt
+```bash
+claude plugin marketplace add onlycastle/BetterPrompt
+claude plugin install betterprompt@betterprompt
 ```
 
 That's it. The MCP server, analysis skills, and post-session hooks are registered automatically.
 
-If `autoAnalyze` is enabled, BetterPrompt can queue an analysis at session end and inject startup context in the next Claude Code session so the queued run resumes automatically.
+### 2. First-time setup
 
-### 2. Run your analysis
+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
 
 In any Claude Code session, run:
 
@@ -50,6 +56,8 @@ In any Claude Code session, run:
 
 The plugin orchestrates the full pipeline -- scan sessions, extract data, analyze each domain, classify your type, and serve a report at `http://localhost:3456`.
 
+If `autoAnalyze` is enabled, BetterPrompt can queue an analysis at session end and inject startup context in the next Claude Code session so the queued run resumes automatically.
+
 ### Available Commands
 
 | Command | Description |
@@ -63,10 +71,10 @@ The plugin orchestrates the full pipeline -- scan sessions, extract data, analyz
 
 ### Uninstalling
 
-In any Claude Code session, run:
+In your terminal:
 
-```
-/plugin uninstall betterprompt@betterprompt
+```bash
+claude plugin uninstall betterprompt@betterprompt
 ```
 
 To also remove local analysis data (results, reports, caches):

docs/agent/PLUGIN.md

@@ -28,6 +28,7 @@ Claude Code plugin at `packages/plugin/`. MCP server + queued auto-analysis hook
 | `lib/report-template.ts` | Standalone HTML report generator |
 | `lib/evaluation-assembler.ts` | Assembles canonical run from results DB |
 | `lib/api-client.ts` | HTTP client, `fetchUserSummary()`, `verifyAuth()` |
+| `lib/prefs.ts` | User preferences (`~/.betterprompt/prefs.json`), first-run detection |
 | `lib/debounce.ts` | Debounce rules, state file read/write |
 | `lib/background-analyzer.ts` | Deprecated cutover stub kept only to fail loudly if invoked |
 | `lib/core/session-scanner.ts` | Claude Code JSONL parsing and local data-dir helpers |
@@ -46,8 +47,10 @@ Claude Code plugin at `packages/plugin/`. MCP server + queued auto-analysis hook
 | `lib/scanner/sources/sqlite-loader.ts` | Shared SQLite loader for Cursor sources |
 | `lib/scanner/tool-mapping.ts` | Tool name normalization across sources |
 | `hooks/post-session-handler.ts` | `SessionEnd` hook, <1.5s, queues the next local analysis run |
-| `hooks/session-start-handler.ts` | `SessionStart` hook, injects queued `/bp-analyze` context |
+| `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-analyze/SKILL.md` | Full analysis pipeline orchestrator skill |
 | `.claude-plugin/plugin.json` | Plugin metadata + config schema |
 | `.mcp.json` | MCP server config (stdio transport) |
 
@@ -112,6 +115,7 @@ Route implementation: `app/api/analysis/user/summary/route.ts`
 | `~/.betterprompt/current-run-id.txt` | Text | Active analysis run ID for cross-tool coordination |
 | `~/.betterprompt/scan-cache/` | JSON | Parsed session cache from multi-source scanner |
 | `~/.betterprompt/reports/` | HTML | Generated reports (`report-{timestamp}.html`, `latest.html`) |
+| `~/.betterprompt/prefs.json` | JSON | User preferences: `welcomeCompleted`, `welcomeVersion`, `starAsked` |
 | `~/.betterprompt/plugin-state.json` | JSON | Lifecycle state: `idle/pending/running/complete/failed` + timestamps |
 | `~/.betterprompt/plugin-errors.log` | Text | Timestamped hook/deprecation errors |
 
@@ -186,6 +190,7 @@ Discovery for Claude Code data dirs uses a waterfall: default `~/.claude/` path,
   - `node ./dist/hooks/session-start-handler.js`
   - `node ./dist/hooks/post-session-handler.js`
 - `SessionEnd` queues work; `SessionStart` injects context so Claude Code consumes the queued run in-band
+- `SessionStart` priority: (1) skip `compact`, (2) first-run → `/bp-setup`, (3) pending analysis → `/bp-analyze`, (4) no-op
 
 ## Build