feat(plugin): project filtering + native deps refactor + command syntax

README.md

@@ -39,18 +39,18 @@ That's it. The MCP server, analysis skills, and post-session hooks are registere
 
 ### 2. 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:
+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
+bp setup
 ```
 
 ### 3. Run your analysis
 
 In any Claude Code session, run:
 
 ```
-/bp-analyze
+bp analyze
 ```
 
 The plugin orchestrates the full pipeline -- scan sessions, extract data, analyze each domain, classify your type, and serve a report at `http://localhost:3456`.
@@ -61,12 +61,12 @@ If `autoAnalyze` is enabled, BetterPrompt can queue an analysis at session end a
 
 | Command | Description |
 |---------|-------------|
-| `/bp-analyze` | Run the full analysis pipeline: scan, extract, analyze 5 domains, classify type, generate report |
-| `/summarize-sessions` | Generate a concise 1-line summary for each analyzed session |
-| `/summarize-projects` | Generate project-level summaries from session data |
-| `/generate-weekly-insights` | Create a "This Week" narrative with stats and highlights |
-| `/classify-type` | Classify your developer type into the 5x3 matrix with narrative |
-| `/translate-report` | Translate report output for non-English sessions |
+| `bp analyze` | Run the full analysis pipeline: scan, extract, analyze 5 domains, classify type, generate report |
+| `summarize sessions` | Generate a concise 1-line summary for each analyzed session |
+| `summarize projects` | Generate project-level summaries from session data |
+| `generate weekly insights` | Create a "This Week" narrative with stats and highlights |
+| `classify type` | Classify your developer type into the 5x3 matrix with narrative |
+| `translate report` | Translate report output for non-English sessions |
 
 ### Uninstalling
 

docs/agent/PLUGIN.md

@@ -48,10 +48,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 |
-| `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 |
+| `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 (includes mid-session MCP registration via `claude mcp add`) |
+| `skills/bp-setup/SKILL.md` | Guided onboarding wizard skill (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) |
@@ -62,8 +62,8 @@ Claude Code plugin at `packages/plugin/`. MCP server + queued auto-analysis hook
 
 | Tool | Parameters | Returns |
 |------|-----------|---------|
-| `scan_sessions` | none | `{ sessionCount, projectCount, projects, sources, totalMessages, dateRange, analysisState }` |
-| `extract_data` | `maxSessions?: number` (default 50) | `{ runId, metrics, deterministicScores }` |
+| `scan_sessions` | `includeProjects?: string[]` | `{ sessionCount, projectCount, projects, allProjects, sources, totalMessages, dateRange, analysisState }` |
+| `extract_data` | `maxSessions?: number` (default 50), `includeProjects?: string[]` | `{ runId, metrics, deterministicScores }` |
 | `save_domain_results` | `domain: enum`, `overallScore`, `strengths[]`, `growthAreas[]`, `data?: {}` | `{ domain, score, runId }` |
 | `get_domain_results` | `domain?: enum` | Single domain or all saved domains |
 | `classify_developer_type` | none | `{ primaryType, controlLevel, matrixName, matrixEmoji, distribution }` |
@@ -117,7 +117,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/prefs.json` | JSON | User preferences: `welcomeCompleted`, `welcomeVersion`, `starAsked`, `selectedProjects` |
 | `~/.betterprompt/plugin-state.json` | JSON | Lifecycle state: `idle/pending/running/complete/failed` + timestamps |
 | `~/.betterprompt/plugin-errors.log` | Text | Timestamped hook/deprecation errors |
 
@@ -146,21 +146,17 @@ Evaluated in order by `shouldTriggerAnalysis(sessionDurationMs)`:
 
 Session count: scans `~/.claude/projects/*/` for `.jsonl` files (filesystem only, no content reading).
 
-## Single-Session Install Flow
+## Native Dependency Resolution
 
-After `/plugin install`, the MCP server isn't running yet (plugin lifecycle starts next session). The `/bp-setup` skill handles this with Step 0.5:
+`ensureNativeDeps({ pluginRoot })` installs `better-sqlite3` to `<pluginRoot>/node_modules/`. Both `server-entry.ts` and `session-start-handler.ts` derive `pluginRoot` by walking up 2 directories from their `dist/` location. Node's standard module resolution finds the native addon by walking up from `dist/mcp/server-entry.js` → `node_modules/better-sqlite3/`.
 
-```
-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.
+No `NODE_PATH` or `CLAUDE_PLUGIN_DATA` env vars are needed. The `.mcp.json` uses a clean config without env overrides.
 
 ## Queued Auto-Analysis Flow
 
 ```
 SessionEnd hook → shouldTriggerAnalysis() → markAnalysisPending()
-SessionStart hook → inject queued `/bp-analyze` context
+SessionStart hook → inject queued `bp analyze` context
 extract_data → markAnalysisStarted()
 generate_report / sync_to_team → markAnalysisComplete()
 ```
@@ -202,7 +198,8 @@ 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
+- `SessionStart` priority: (1) skip `compact`, (2) first-run → `bp setup`, (3) pending analysis → `bp analyze`, (4) no-op
+- Both hooks derive `pluginRoot` for `ensureNativeDeps()` via `join(dirname(fileURLToPath(import.meta.url)), '..', '..')`
 
 ## Build
 

docs/human/PLUGIN.md

@@ -28,7 +28,7 @@ Developer uses Claude Code normally
              v
     +-------------------+
     |  Next SessionStart |
-    |  injects `/bp-analyze`|
+    |  injects `bp analyze` |
     +--------+----------+
              |
              +-->  Scan sessions (~/.claude/projects/, Cursor)
@@ -79,10 +79,11 @@ This prevents over-analyzing short sessions or re-analyzing too frequently.
 
 When Claude Code consumes the queued BetterPrompt context, the plugin:
 
-1. Scans supported local session sources
-2. Runs deterministic extraction and typed stage persistence
-3. Executes the domain/type/content/translation skills inside Claude Code
-4. Generates the local report and optionally syncs the canonical run to the dashboard
+1. Reads `selectedProjects` from user preferences (if set during `bp setup`)
+2. Scans supported local session sources (filtered by selected projects)
+3. Runs deterministic extraction and typed stage persistence
+4. Executes the domain/type/content/translation skills inside Claude Code
+5. Generates the local report and optionally syncs the canonical run to the dashboard
 
 ## Setup
 

docs/human/USER-FLOWS.md

@@ -83,10 +83,10 @@ The employee flow covers the individual contributor experience — running analy
 ┌─────────────────────────────────────────────────────────────────────┐
 │                        ANALYSIS PIPELINE                             │
 │                                                                      │
-│   /bp-analyze                                                        │
+│   bp analyze                                                         │
 │        │                                                             │
-│        ├─ 1. scan_sessions — discovers local session logs            │
-│        ├─ 2. extract_data — deterministic Phase 1 extraction         │
+│        ├─ 1. scan_sessions — discovers local session logs (filterable by project) │
+│        ├─ 2. extract_data — deterministic Phase 1 extraction (respects project filter) │
 │        ├─ 3. save_domain_results — LLM analysis per domain          │
 │        ├─ 4. classify_developer_type — 5x3 type matrix              │
 │        ├─ 5. generate_report — HTML report on localhost:3456         │
@@ -107,7 +107,7 @@ The employee flow covers the individual contributor experience — running analy
 │  ┌─────────────────────────────────────────────────┐ │
 │  │  🔌 Use the plugin to analyze your sessions     │ │
 │  │                                                  │ │
-│  │  /bp-analyze                                     │ │
+│  │  bp analyze                                      │ │
 │  │                                                  │ │
 │  └─────────────────────────────────────────────────┘ │
 │                                                       │

docs/superpowers/specs/2026-03-18-agents-md-onboarding-design.md

@@ -20,7 +20,7 @@ Replace the current AGENTS.md with a persona-based onboarding flow:
    - **Individual Developer:** Plugin install only (2 commands, no server/keys/cloning)
    - **Team Manager:** Plugin install + clone repo + start dashboard server
 3. **Soft onboarding** — Each path ends with a "What to do next" sentence:
-   - Individual: "Run `/bp-analyze` to start your first analysis"
+   - Individual: "Run `bp analyze` to start your first analysis"
    - Team Manager: "Visit `/dashboard/enterprise/setup` to create your org and invite members"
 
 ### Content Removed from AGENTS.md
@@ -76,7 +76,7 @@ Install the Claude Code plugin. No server, no API keys, no cloning needed.
 /plugin install betterprompt@betterprompt
 ```
 
-**What to do next:** Run `/bp-analyze` in any Claude Code session. The plugin queues analysis automatically when enough new sessions accumulate. Reports are served at `http://localhost:3456`.
+**What to do next:** Run `bp analyze` in any Claude Code session. The plugin queues analysis automatically when enough new sessions accumulate. Reports are served at `http://localhost:3456`.
 
 ### Team Manager
 

packages/plugin/.mcp.json

@@ -2,10 +2,7 @@
   "mcpServers": {
     "betterprompt": {
       "command": "node",
-      "args": ["./dist/mcp/server-entry.js"],
-      "env": {
-        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
-      }
+      "args": ["./dist/mcp/server-entry.js"]
     }
   }
 }