bluera-knowledge 0.28.1 → 0.30.0

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [0.30.0](https://github.com/blueraai/bluera-knowledge/compare/v0.28.0...v0.30.0) (2026-02-21)
+
+
+### Features
+
+* **mcp:** add file count estimation and ETA to store creation responses ([3d71a30](https://github.com/blueraai/bluera-knowledge/commit/3d71a307275fa06b9810ed606583f4ec2acc5841))
+* **mcp:** add stores:pull command for git pull + re-index ([7ca809c](https://github.com/blueraai/bluera-knowledge/commit/7ca809c3675be19d9d0e29e71c5f75d4f40fce35))
+* search infrastructure, benchmark framework, and model registry ([285ff2f](https://github.com/blueraai/bluera-knowledge/commit/285ff2f5574c4d53b61b31e84fdec43553364e98))
+* training pipeline, evaluation gate, and experiment docs ([d90b395](https://github.com/blueraai/bluera-knowledge/commit/d90b395a330f4ab09ac6d71db77d659c415aa87d))
+
+
+### Bug Fixes
+
+* **config:** wire BK_MODEL env var override in ConfigService.load() ([be56426](https://github.com/blueraai/bluera-knowledge/commit/be564263176410c3eb1441bf85c4fdce48ddc7c4))
+* **mcp:** prevent browser postinstall from crashing bootstrap ([e27fe02](https://github.com/blueraai/bluera-knowledge/commit/e27fe021bdb34c8ca5b8bf93720a176435e7973c))
+
+## [0.29.0](https://github.com/blueraai/bluera-knowledge/compare/v0.28.0...v0.29.0) (2026-02-20)
+
+
+### Features
+
+* search infrastructure, benchmark framework, and model registry ([285ff2f](https://github.com/blueraai/bluera-knowledge/commit/285ff2f5574c4d53b61b31e84fdec43553364e98))
+* training pipeline, evaluation gate, and experiment docs ([d90b395](https://github.com/blueraai/bluera-knowledge/commit/d90b395a330f4ab09ac6d71db77d659c415aa87d))
+
+
+### Bug Fixes
+
+* **config:** wire BK_MODEL env var override in ConfigService.load() ([be56426](https://github.com/blueraai/bluera-knowledge/commit/be564263176410c3eb1441bf85c4fdce48ddc7c4))
+* **mcp:** prevent browser postinstall from crashing bootstrap ([e27fe02](https://github.com/blueraai/bluera-knowledge/commit/e27fe021bdb34c8ca5b8bf93720a176435e7973c))
+
 ## [0.28.1](https://github.com/blueraai/bluera-knowledge/compare/v0.28.0...v0.28.1) (2026-02-12)
 
 ## [0.28.0](https://github.com/blueraai/bluera-knowledge/compare/v0.27.3...v0.28.0) (2026-02-10)

package/README.md

@@ -339,7 +339,7 @@ This architecture means commands provide a clean user interface while MCP tools
 | `execute` | ⚡ Meta-tool for store/job management commands |
 
 The `execute` tool consolidates store and job management into a single tool with subcommands:
-- **Store commands**: `stores`, `store:info`, `store:create`, `store:index`, `store:delete`
+- **Store commands**: `stores`, `store:info`, `store:create`, `store:index`, `store:delete`, `stores:pull`
 - **Job commands**: `jobs`, `job:status`, `job:cancel`
 - **Help**: `help`, `commands`
 
@@ -452,18 +452,200 @@ Combine canonical library code with project-specific patterns:
 
 ## 🔧 Troubleshooting
 
-Run `/bluera-knowledge:doctor` for quick diagnostics (works even when MCP is broken).
+### Quick Diagnostics
 
-**Common issues:** See [docs/troubleshooting.md](docs/troubleshooting.md) for solutions to:
-- Command not found or not recognized
-- MCP server failures
-- Web crawling issues
-- Search returning no results
-- Model mismatch errors
-- Native module compilation (Node.js v24)
-- Linux build tool requirements
-- Slow indexing
-- Log viewing and debugging
+Run `/bluera-knowledge:doctor` to diagnose common issues. This checks:
+- Build tools (make/gcc) - required for native modules
+- Node.js installation
+- Plugin dependencies (node_modules)
+- MCP wrapper installation
+- Python 3 (optional, for embeddings)
+- Playwright browser (optional, for web crawling)
+
+Works even when MCP is broken (uses Bash tool directly).
+
+<details>
+<summary><b>❌ Command not found or not recognized</b></summary>
+
+Ensure the plugin is installed and enabled:
+
+```bash
+/plugin list
+/plugin enable bluera-knowledge
+```
+
+If the plugin isn't listed, install it:
+
+```bash
+/plugin marketplace add blueraai/bluera-marketplace
+/plugin install bluera-knowledge@bluera
+```
+</details>
+
+<details>
+<summary><b>🔌 MCP server shows as "failed" in /plugin</b></summary>
+
+If the MCP server shows as failed after installation:
+
+1. **Run `/bluera-knowledge:doctor`** - This diagnoses the most common issues
+2. **Restart Claude Code** - MCP servers require a restart to initialize
+3. **Check logs:** Run `/logs errors` to see recent errors or `/logs module bootstrap` for startup logs
+4. **Check status:** Run `/mcp` to see connection status
+5. **Reinstall:** Try `/plugin uninstall bluera-knowledge` then `/plugin install bluera-knowledge@bluera`
+
+**Common MCP failure causes:**
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `npm ERR! ERESOLVE` in logs | Peer dependency conflict | Fixed in v0.22.6+ with npm flag |
+| Old plugin version running | Multiple cached versions | Fixed in v0.22.7+ (version sorting) |
+| `make not found` | Missing build tools | Install `build-essential` (Linux) |
+| Compilation errors on Node 24 | V8 API changes | Use Node.js v20.x or v22.x |
+
+If the issue persists, check that Claude Code is v2.0.65 or later (earlier versions had MCP loading bugs).
+</details>
+
+<details>
+<summary><b>🌐 Web crawling fails</b></summary>
+
+Check Playwright browser installation:
+
+```bash
+npx playwright install chromium
+```
+
+The plugin attempts to auto-install Playwright browsers on first use, but manual installation may be needed in some environments.
+</details>
+
+<details>
+<summary><b>🔍 Search returns no results</b></summary>
+
+1. Verify store exists: `/bluera-knowledge:stores`
+2. Check store is indexed: `/bluera-knowledge:index <store-name>`
+3. Try broader search terms
+4. Verify you're searching the correct store with `--stores=<name>`
+</details>
+
+<details>
+<summary><b>⚠️ "Model mismatch" error</b></summary>
+
+This error occurs when a store was indexed with a different embedding model than the current configuration. As of v0.20+, stores are indexed with `bge-small-en-v1.5` (previously `all-MiniLM-L6-v2`).
+
+**Solution:** Reindex the affected store:
+
+```bash
+/bluera-knowledge:index <store-name>
+```
+
+**Check model status for all stores:**
+
+```bash
+# Via MCP execute command
+execute stores:check-models
+```
+
+This lists all stores with their embedding model and flags any that need reindexing.
+</details>
+
+<details>
+<summary><b>❓ "Store not found" error</b></summary>
+
+List all stores to see available names and IDs:
+
+```bash
+/bluera-knowledge:stores
+```
+
+Use the exact store name or ID shown in the table.
+</details>
+
+<details>
+<summary><b>🔨 Native module compilation fails (Node.js v24)</b></summary>
+
+tree-sitter and lancedb require native module compilation. Node.js v24 introduced V8 API changes that break these modules.
+
+**Solution:** Use Node.js v20.x or v22.x (LTS versions):
+
+```bash
+# Using nvm
+nvm install 22
+nvm use 22
+```
+
+Run `/bluera-knowledge:doctor` to verify your environment.
+</details>
+
+<details>
+<summary><b>🐧 Linux: "make not found" or build errors</b></summary>
+
+Native modules require build tools:
+
+```bash
+# Debian/Ubuntu
+sudo apt install build-essential
+
+# Fedora/RHEL
+sudo dnf groupinstall "Development Tools"
+```
+
+Then restart Claude Code for auto-setup to complete.
+</details>
+
+<details>
+<summary><b>⏱️ Indexing is slow or fails</b></summary>
+
+Large repositories (10,000+ files) take longer to index. If indexing fails:
+
+1. Check available disk space
+2. Ensure the source repository/folder is accessible
+3. For repo stores, verify git is installed: `git --version`
+4. Check for network connectivity (for repo stores)
+5. Check logs for errors: `/logs errors` or `/logs search "index"`
+</details>
+
+<details>
+<summary><b>🤖 "Claude CLI not found" during crawl</b></summary>
+
+This means intelligent crawling is unavailable. The crawler will automatically use simple BFS mode instead.
+
+To enable intelligent crawling with `--crawl` and `--extract`:
+1. Install Claude Code: https://claude.com/code
+2. Ensure `claude` command is in PATH: `which claude`
+
+Simple mode still crawls effectively—it just doesn't use AI to select which pages to crawl or extract specific content.
+</details>
+
+<details>
+<summary><b>📋 How to view logs for debugging</b></summary>
+
+The plugin logs all MCP server operations to `.bluera/bluera-knowledge/logs/app.log` (relative to project root).
+
+**View logs using the `/logs` command:**
+
+```bash
+/logs              # Watch logs in real-time (tail -f)
+/logs view 50      # View last 50 log entries
+/logs errors       # Show only error-level logs
+/logs module mcp-store  # Filter by module (mcp-server, mcp-store, mcp-execute, mcp-job, mcp-sync, bootstrap)
+/logs search "pattern"  # Search for a pattern
+```
+
+**Log modules:**
+- `bootstrap` - MCP server startup and dependency installation
+- `mcp-server` - Core MCP server operations
+- `mcp-store` - Store create/list/delete operations
+- `mcp-search` - Search queries and results
+- `mcp-execute` - Meta-tool command execution
+- `mcp-job` - Background job status
+- `mcp-sync` - Store sync operations
+
+**Manual access:**
+```bash
+tail -f .bluera/bluera-knowledge/logs/app.log
+```
+
+Logs are JSON formatted (NDJSON) and can be processed with `jq` for pretty-printing.
+</details>
 
 ---
 
@@ -645,7 +827,6 @@ This ensures:
 | [Commands Reference](docs/commands.md) | All slash commands with parameters and examples |
 | [Crawler Architecture](docs/crawler-architecture.md) | How the intelligent web crawler works |
 | [Token Efficiency](docs/token-efficiency.md) | How BK reduces token consumption vs web search |
-| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
 | [CONTRIBUTING](CONTRIBUTING.md) | Development setup, testing, and release process |
 
 ---