refactor(plugin): file logging, install diagnostics, and UI polish

README.md

@@ -68,6 +68,24 @@ If `autoAnalyze` is enabled, BetterPrompt can queue an analysis at session end a
 | `classify type` | Classify your developer type into the 5x3 matrix with narrative |
 | `translate report` | Translate report output for non-English sessions |
 
+### Troubleshooting
+
+If the plugin isn't working, run the verification script:
+
+```bash
+bash scripts/verify-plugin.sh
+```
+
+This checks all 8 components (build artifacts, native dependencies, MCP config, plugin registration, server startup, session files) and reports what's broken with fix instructions.
+
+**Common issues:**
+
+| 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 |
+| Rate limits during analysis | Reduce scope: select fewer projects in `bp setup`, or run analysis during off-peak hours |
+
 ### Uninstalling
 
 In Claude Code:

docs/agent/PLUGIN.md

@@ -21,7 +21,7 @@ Claude Code plugin at `packages/plugin/`. MCP server + queued auto-analysis hook
 | `mcp/tools/get-developer-profile.ts` | Tool (server-backed): profile type, scores, personality |
 | `mcp/tools/get-growth-areas.ts` | Tool (server-backed): growth areas, optional domain filter |
 | `mcp/tools/get-recent-insights.ts` | Tool (server-backed): strengths / anti-patterns / KPT |
-| `lib/logger.ts` | Structured stderr logger (`debug`/`info`/`error`). `debug` requires `BETTERPROMPT_DEBUG=1`; `info` and `error` always emit |
+| `lib/logger.ts` | Dual-destination logger (`debug`/`info`/`error`). All levels write to `~/.betterprompt/debug.log` (timestamped). Stderr: `debug` requires `BETTERPROMPT_DEBUG=1`; `info` and `error` always emit |
 | `lib/config.ts` | Plugin settings reader, path helpers |
 | `lib/cache.ts` | SQLite cache (better-sqlite3, WAL mode) |
 | `lib/results-db.ts` | SQLite results database for canonical analysis runs |
@@ -122,6 +122,7 @@ Route implementation: `app/api/analysis/user/summary/route.ts`
 | `~/.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 |
+| `~/.betterprompt/debug.log` | Text | All logger output (debug/info/error) with ISO timestamps, written unconditionally |
 
 ## Cache Behavior
 

next-env.d.ts

@@ -1,6 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
-import "./.next/types/routes.d.ts";
+import "./.next/dev/types/routes.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

packages/plugin/.mcp.json

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