bluera-knowledge 0.11.13 → 0.11.15

package/.claude/commands/test-plugin.md

@@ -0,0 +1,148 @@
+# Test Plugin
+
+Comprehensive test of all Bluera Knowledge plugin functionality (MCP tools + slash commands).
+
+## Context
+
+!`echo "=== BK Plugin Test ===" && ls -la .bluera/bluera-knowledge/ 2>/dev/null || echo "No BK data dir yet (will be created)"`
+
+## Test Content Setup
+
+First, create test content for indexing:
+
+```bash
+mkdir -p .bluera/bluera-knowledge/test-content
+cat > .bluera/bluera-knowledge/test-content/test-file.md << 'EOF'
+# BK Plugin Test File
+
+This file contains unique test content for validating the Bluera Knowledge plugin.
+
+## Test Function
+
+The `validateBKPlugin` function performs comprehensive testing of all plugin features.
+It checks MCP connectivity, store operations, search functionality, and cleanup.
+
+Keywords: bluera-knowledge-test, plugin-validation, mcp-test
+EOF
+```
+
+## Workflow
+
+Execute each test in order. Mark each as PASS or FAIL.
+
+### Part 1: MCP Tools
+
+1. **MCP Connection**: Call MCP tool `execute` with `{ command: "help" }`
+   - Expected: Returns list of available commands
+   - PASS if response contains "Available commands"
+
+2. **List Stores (MCP)**: Call MCP tool `execute` with `{ command: "stores" }`
+   - Expected: Returns store list (may be empty initially)
+   - PASS if no error
+
+3. **Create Store**: Call MCP tool `execute` with:
+   ```json
+   { "command": "store:create", "args": { "name": "bk-test-store", "type": "file", "path": ".bluera/bluera-knowledge/test-content" } }
+   ```
+   - Expected: Store created successfully
+   - PASS if response indicates success
+
+4. **Store Info**: Call MCP tool `execute` with:
+   ```json
+   { "command": "store:info", "args": { "store": "bk-test-store" } }
+   ```
+   - Expected: Returns store metadata including name, type, path
+   - PASS if response contains store details
+
+5. **Index Store**: Call MCP tool `execute` with:
+   ```json
+   { "command": "store:index", "args": { "store": "bk-test-store" } }
+   ```
+   - Expected: Indexing completes (may take a few seconds)
+   - PASS if response indicates indexing succeeded
+
+6. **Search (MCP)**: Call MCP tool `search` with:
+   ```json
+   { "query": "validateBKPlugin", "stores": ["bk-test-store"] }
+   ```
+   - Expected: Returns results containing test content
+   - PASS if results array is non-empty and contains test file
+
+7. **Get Full Context**: If search returned results, call MCP tool `get_full_context` with:
+   ```json
+   { "resultId": "<id from search result>" }
+   ```
+   - Expected: Returns full file content
+   - PASS if response contains "BK Plugin Test File"
+
+### Part 2: Slash Commands
+
+8. **Stores Command**: Run `/bluera-knowledge:stores`
+   - Expected: Shows bk-test-store in output
+   - PASS if store is listed
+
+9. **Search Command**: Run `/bluera-knowledge:search "bluera-knowledge-test"`
+   - Expected: Returns results from test store
+   - PASS if results are shown
+
+10. **Suggest Command**: Run `/bluera-knowledge:suggest`
+    - Expected: Runs without error (may show no suggestions if no package.json)
+    - PASS if no error thrown
+
+### Part 3: Cleanup
+
+11. **Delete Store**: Call MCP tool `execute` with:
+    ```json
+    { "command": "store:delete", "args": { "store": "bk-test-store" } }
+    ```
+    - Expected: Store deleted
+    - PASS if deletion succeeds
+
+12. **Remove Test Content**: Run bash command:
+    ```bash
+    rm -rf .bluera/bluera-knowledge/test-content
+    ```
+    - Expected: Directory removed
+    - PASS if command succeeds
+
+13. **Verify Cleanup**: Call MCP tool `execute` with `{ command: "stores" }`
+    - Expected: bk-test-store is NOT in the list
+    - PASS if test store is gone
+
+## Output Format
+
+After running all tests, report results in this format:
+
+### Plugin Test Results
+
+| # | Test | Status |
+|---|------|--------|
+| 1 | MCP Connection (help) | ? |
+| 2 | List Stores (MCP) | ? |
+| 3 | Create Store | ? |
+| 4 | Store Info | ? |
+| 5 | Index Store | ? |
+| 6 | Search (MCP) | ? |
+| 7 | Get Full Context | ? |
+| 8 | /stores Command | ? |
+| 9 | /search Command | ? |
+| 10 | /suggest Command | ? |
+| 11 | Delete Store | ? |
+| 12 | Remove Test Content | ? |
+| 13 | Verify Cleanup | ? |
+
+**Result: X/13 tests passed**
+
+## Error Recovery
+
+If tests fail partway through, clean up manually:
+
+1. Delete test store (if exists):
+   ```
+   execute → { command: "store:delete", args: { store: "bk-test-store" } }
+   ```
+
+2. Remove test content directory:
+   ```bash
+   rm -rf .bluera/bluera-knowledge/test-content
+   ```

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.11.13",
+  "version": "0.11.15",
   "description": "Clone repos, crawl docs, search locally. Fast, authoritative answers for AI coding agents.",
   "mcpServers": {
     "bluera-knowledge": {

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 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.11.15](https://github.com/blueraai/bluera-knowledge/compare/v0.11.6...v0.11.15) (2026-01-10)
+
+
+### Features
+
+* **commands:** add test-plugin command for comprehensive plugin testing ([f50c47f](https://github.com/blueraai/bluera-knowledge/commit/f50c47fee74df8c1efbe23481f05dfa33c62911f))
+* **scripts:** add post-release npm validation script ([e4c29a0](https://github.com/blueraai/bluera-knowledge/commit/e4c29a0c83907de4bc293a69a58412629457fb22))
+* **scripts:** add suggest, sync, serve, mcp tests to npm validation ([49d85da](https://github.com/blueraai/bluera-knowledge/commit/49d85dad1a89691060c12f152d644844baf6e6e6))
+* **scripts:** log expected vs installed version in validation script ([c77d039](https://github.com/blueraai/bluera-knowledge/commit/c77d039b27a3ccf54d50006af161ac4dcfea7b21))
+
+
+### Bug Fixes
+
+* **cli:** plugin-api commands now respect global options ([d3cca02](https://github.com/blueraai/bluera-knowledge/commit/d3cca02ffc679ffc187b76c7682f3cc177eabdea))
+* **plugin:** properly close services after command execution ([eeaf743](https://github.com/blueraai/bluera-knowledge/commit/eeaf743750be73fd9c7a9e72440b2fd0fb5a53fa))
+* **scripts:** show real-time output in validation script ([8a4bdec](https://github.com/blueraai/bluera-knowledge/commit/8a4bdec8b63c504d34ba35bfe19da795f7f7fd07))
+* **scripts:** use mktemp for temp directories in validation script ([3107861](https://github.com/blueraai/bluera-knowledge/commit/3107861bd7a966016fde2a121469dd84756f39be))
+* **search:** add defaults for env vars so CLI works standalone ([b2d2ce5](https://github.com/blueraai/bluera-knowledge/commit/b2d2ce534e8cd2ba0fc0abdac505c912a1a76035))
+
+## [0.11.14](https://github.com/blueraai/bluera-knowledge/compare/v0.11.6...v0.11.14) (2026-01-10)
+
+
+### Features
+
+* **scripts:** add post-release npm validation script ([e4c29a0](https://github.com/blueraai/bluera-knowledge/commit/e4c29a0c83907de4bc293a69a58412629457fb22))
+* **scripts:** add suggest, sync, serve, mcp tests to npm validation ([49d85da](https://github.com/blueraai/bluera-knowledge/commit/49d85dad1a89691060c12f152d644844baf6e6e6))
+* **scripts:** log expected vs installed version in validation script ([c77d039](https://github.com/blueraai/bluera-knowledge/commit/c77d039b27a3ccf54d50006af161ac4dcfea7b21))
+
+
+### Bug Fixes
+
+* **cli:** plugin-api commands now respect global options ([d3cca02](https://github.com/blueraai/bluera-knowledge/commit/d3cca02ffc679ffc187b76c7682f3cc177eabdea))
+* **plugin:** properly close services after command execution ([eeaf743](https://github.com/blueraai/bluera-knowledge/commit/eeaf743750be73fd9c7a9e72440b2fd0fb5a53fa))
+* **scripts:** show real-time output in validation script ([8a4bdec](https://github.com/blueraai/bluera-knowledge/commit/8a4bdec8b63c504d34ba35bfe19da795f7f7fd07))
+* **scripts:** use mktemp for temp directories in validation script ([3107861](https://github.com/blueraai/bluera-knowledge/commit/3107861bd7a966016fde2a121469dd84756f39be))
+* **search:** add defaults for env vars so CLI works standalone ([b2d2ce5](https://github.com/blueraai/bluera-knowledge/commit/b2d2ce534e8cd2ba0fc0abdac505c912a1a76035))
+
 ## [0.11.13](https://github.com/blueraai/bluera-knowledge/compare/v0.11.6...v0.11.13) (2026-01-10)
 
 

package/README.md

@@ -122,6 +122,47 @@ Bluera Knowledge enables option 3 by building a searchable knowledge base from *
 
 ---
 
+## 🎯 When Claude Code Should Query BK
+
+**The simple rule: Query BK for any question about libraries, dependencies, or reference material.**
+
+BK is cheap (~100ms, no rate limits), authoritative (actual source code), and complete (includes tests and internal APIs). Claude Code should query it frequently for external code questions.
+
+### Always Query BK For:
+
+| Question Type | Examples |
+|--------------|----------|
+| **Library internals** | "How does Express handle middleware errors?", "What does useEffect cleanup do?" |
+| **API signatures** | "What parameters does axios.create() accept?", "What options can I pass to Hono?" |
+| **Error handling** | "What errors can Zod throw?", "Why might this library return undefined?" |
+| **Version behavior** | "What changed in React 18?", "Is this method deprecated?" |
+| **Configuration** | "What config options exist for Vite?", "What are the defaults?" |
+| **Testing patterns** | "How do the library authors test this?", "How should I mock this?" |
+| **Performance/internals** | "Is this cached internally?", "What's the complexity?" |
+| **Security** | "How does this library validate input?", "Is this safe against injection?" |
+| **Integration** | "How do I integrate X with Y?", "What's the idiomatic way to use this?" |
+
+### DO NOT Query BK For:
+
+| Question Type | Use Instead |
+|--------------|-------------|
+| **Your project code** | Grep/Read directly ("Where is OUR auth middleware?") |
+| **General concepts** | Training data ("What is a closure?") |
+| **Breaking news** | Web search ("Latest React release notes") |
+
+### Quick Pattern Matching:
+
+```
+"How does [library] work..."           → Query BK
+"What does [library function] do..."   → Query BK
+"What options does [library] accept..."→ Query BK
+"What errors can [library] throw..."   → Query BK
+"Where is [thing] in OUR code..."      → Grep/Read directly
+"What is [general concept]..."         → Training data
+```
+
+---
+
 ## 💰 Token Efficiency
 
 Beyond speed and accuracy, Bluera Knowledge can **significantly reduce token consumption** for code-related queries—typically saving 60-75% compared to web search approaches.
@@ -196,12 +237,15 @@ Bluera Knowledge isn't always the most token-efficient choice:
 
 ### 💡 Best Practice
 
-Let Claude Code decide when to use Bluera Knowledge:
-- For **library-specific, version-specific, or implementation questions** → BK saves tokens and increases accuracy
-- For **general programming concepts** → Training data is more efficient
-- For **current events** → Web search is necessary
+**Default to BK for library questions.** It's cheap, fast, and authoritative:
 
-The plugin's Skills teach Claude Code these patterns, so it automatically uses the most efficient approach for each question.
+| Question Type | Action | Why |
+|--------------|--------|-----|
+| Library internals, APIs, errors, versions, config | **Query BK first** | Source code is definitive, 60-85% token savings |
+| General programming concepts | Skip BK | Training data is sufficient |
+| Breaking news, release notes | Web search | BK only has indexed content |
+
+The plugin's Skills teach Claude Code these patterns automatically. When in doubt about a dependency, query BK—it's faster and more accurate than guessing or web searching.
 
 ---
 
@@ -1617,6 +1661,21 @@ This script:
 
 Use this to catch any packaging or runtime issues after npm publish.
 
+### 🧪 Plugin Self-Test
+
+Test all plugin functionality from within Claude Code:
+
+```
+/test-plugin
+```
+
+This command runs 13 tests covering:
+- **MCP Tools**: execute (help, stores, create, info, index), search, get_full_context
+- **Slash Commands**: /stores, /search, /suggest
+- **Cleanup**: Store deletion, artifact removal, verification
+
+The test creates temporary content, exercises all features, and cleans up automatically. Use this to verify the plugin is working correctly after installation or updates.
+
 ### 🧪 Testing Locally
 
 **Option 1: Development MCP Server (Recommended)**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.11.13",
+  "version": "0.11.15",
   "description": "CLI tool for managing knowledge stores with semantic search",
   "type": "module",
   "bin": {

package/skills/knowledge-search/SKILL.md

@@ -7,40 +7,85 @@ description: Teaches how to use Bluera Knowledge for accessing library sources a
 
 BK provides access to **definitive library sources** for your project dependencies.
 
-## Purpose: Authoritative References, Not Project Search
+## The Rule: Query BK for External Code
 
-**CKB is for**: Reference material and external sources
-- **Library sources**: Clone Vue.js/Pydantic/Hono for authoritative API reference
-- **Specifications**: Add project requirements, API specs, RFCs
-- **Documentation**: Add design docs, architecture guides, research papers
-- **Reference material**: Best practices, coding standards, examples
+**Any question about libraries, dependencies, or indexed reference material should query BK.**
 
-**CKB is NOT for**: Searching your current project code
-- Use Grep/Read directly on project files
-- BK stores are for external reference material
+BK is:
+- **Cheap**: ~100ms response, unlimited queries, no rate limits
+- **Authoritative**: Actual source code, not blog posts or training data
+- **Complete**: Includes tests, examples, internal APIs, configuration
+
+## Always Query BK For:
+
+**Library implementation:**
+- "How does Express handle middleware errors?"
+- "What does React's useEffect cleanup actually do?"
+- "How is Pydantic validation implemented?"
+
+**API signatures and options:**
+- "What parameters does axios.create() accept?"
+- "What options can I pass to hono.use()?"
+- "What's the signature of zod.object()?"
+
+**Error handling:**
+- "What errors can this library throw?"
+- "Why might this function return undefined?"
+- "What validation does Zod perform?"
+
+**Version-specific behavior:**
+- "What changed in React 18?"
+- "Is this deprecated in Express 5?"
+- "Does my version support this?"
+
+**Configuration:**
+- "What config options exist for Vite?"
+- "What are the default values?"
+- "What environment variables does this use?"
+
+**Testing:**
+- "How do the library authors test this?"
+- "How should I mock this in tests?"
+- "What edge cases do the tests cover?"
+
+**Performance:**
+- "Is this cached internally?"
+- "What's the complexity of this operation?"
+- "Does this run async or sync?"
+
+**Security:**
+- "How does this validate input?"
+- "Is this safe against injection?"
+- "How are credentials handled?"
+
+**Integration:**
+- "How do I integrate X with Y?"
+- "What's the idiomatic usage pattern?"
+- "How do examples in the library do this?"
 
 ## Two Ways to Access Library Sources
 
-### 1. Vector Search (MCP or slash command)
-Find concepts and patterns across library docs:
+### 1. Vector Search (Discovery)
+Find concepts and patterns across indexed content:
 ```
 search("vue reactivity system")
 /bluera-knowledge:search "pydantic custom validators"
 ```
 
-### 2. Direct File Access (Grep/Read)
+### 2. Direct File Access (Precision)
 Precise lookups in cloned library source:
 ```
 Grep: pattern="defineReactive" path=".bluera/bluera-knowledge/repos/vue/"
 Read: .bluera/bluera-knowledge/repos/pydantic/pydantic/validators.py
 ```
 
-## Both Are Valid!
+Both are valid! Use vector search for discovery, Grep/Read for specific functions.
 
-You can use **either or both** approaches on the same cloned repo:
-- Vector search to discover relevant files
-- Grep/Read to find specific functions/classes
-- Or just Grep/Read if you know what you're looking for
+## DO NOT Query BK For:
+
+- **Your project code** → Use Grep/Read directly
+- **General concepts** → Use training data ("What is a closure?")
+- **Breaking news** → Use web search ("Latest React release")
 
 ## Example Workflow
 
@@ -52,3 +97,14 @@ Claude:
 3. Read file: `.bluera/bluera-knowledge/repos/vue/packages/reactivity/src/computed.ts`
 4. Grep for implementation: pattern="class ComputedRefImpl"
 5. Explain with authoritative source code examples
+
+## Quick Reference
+
+```
+[library] question        → Query BK
+[your code] question      → Grep/Read directly
+[concept] question        → Training data
+[news/updates] question   → Web search
+```
+
+BK is cheap and fast. Query it liberally for library questions.

package/skills/when-to-query/SKILL.md

@@ -3,64 +3,158 @@ name: when-to-query
 description: Decision guide for when to query Bluera Knowledge stores vs using Grep/Read on current project. Query BK for library/dependency questions and reference material. Use Grep/Read for current project code, debugging, and implementation details. Includes setup instructions and mental model.
 ---
 
-# When to Query BK vs Current Project
+# When to Query Bluera Knowledge
 
-## Query BK When:
+## The Rule: BK First for External Code
 
-**Questions about libraries/dependencies:**
-- "How does Vue's reactivity system work?"
-- "What are Pydantic's built-in validators?"
-- "How should I use Pino's child loggers?"
-- "What middleware does Hono provide?"
+**When the question involves libraries, dependencies, or reference material, query BK first.**
 
-**Reference material questions:**
-- "What does the API spec say about authentication?"
-- "What are the project requirements for error handling?"
-- "How does the architecture doc describe the data flow?"
-- "What coding standards apply to this project?"
+BK provides authoritative source code from the actual libraries. This is:
+- **More accurate** than training data (which may be outdated)
+- **Faster** than web search (~100ms vs 2-5 seconds)
+- **More complete** than documentation sites (includes tests, examples, internal APIs)
+- **Zero rate limits** (local, unlimited queries)
 
-**Learning library APIs:**
-- Discovering available options/configs
-- Finding usage examples from library itself
-- Understanding internal implementation
+---
 
-**Verifying specifications:**
-- Checking exact requirements
-- Finding edge cases in specs
-- Understanding design decisions
+## ALWAYS Query BK For:
+
+### Library Implementation Questions
+- "How does Express handle middleware errors?"
+- "What does `useEffect` cleanup actually do internally?"
+- "How is Pydantic validation implemented?"
+- "What happens when lodash `debounce` is called?"
+- "How does React's reconciliation work?"
+
+### API and Method Questions
+- "What parameters does `axios.create()` accept?"
+- "What's the signature of `zod.object()`?"
+- "What options can I pass to `hono.use()`?"
+- "What events does EventEmitter emit?"
+- "What methods are available on `prisma.client`?"
+
+### Error and Exception Handling
+- "What errors can this library throw?"
+- "How do I catch validation errors in Zod?"
+- "What does this error code mean in library X?"
+- "Why might this function return undefined?"
+- "What validation does this library perform?"
+
+### Version-Specific Behavior
+- "What changed in React 18's concurrent mode?"
+- "How does this work in Express 4 vs 5?"
+- "Is this method deprecated in the latest version?"
+- "What's the migration path from v2 to v3?"
+- "Does my version support this feature?"
+
+### Configuration and Options
+- "What configuration options exist for Vite?"
+- "What are the default values for these options?"
+- "How do I customize the behavior of X?"
+- "What environment variables does this library use?"
+- "What's the full schema for this config?"
+
+### Testing Patterns
+- "How do the library authors test this feature?"
+- "How should I mock this library in tests?"
+- "What fixtures do I need for testing this integration?"
+- "What edge cases does the library's test suite cover?"
+
+### Performance and Internals
+- "Is this operation cached internally?"
+- "What's the time complexity of this method?"
+- "How is this optimized in the library?"
+- "Does this run synchronously or asynchronously?"
+- "What's the memory footprint of this?"
+
+### Security and Validation
+- "How does this library validate input?"
+- "What sanitization is applied?"
+- "How are credentials handled internally?"
+- "Is this safe against injection attacks?"
+
+### Integration and Patterns
+- "How do I integrate library X with library Y?"
+- "What's the idiomatic way to use this API?"
+- "How do examples in the library do this?"
+- "What patterns does this library use?"
+- "What's the recommended project structure?"
+
+### Reference Material
+- "What does the API spec say about X?"
+- "What are the project requirements for Y?"
+- "How does the architecture doc describe Z?"
+- "What coding standards apply here?"
 
-## Query Current Project (Grep/Read) When:
+---
 
-**Working on YOUR code:**
-- "Where is the authentication middleware?"
-- "Find all API endpoints"
-- "Show me the database models"
+## DO NOT Query BK For:
 
-**Debugging YOUR code:**
-- Reading error traces
-- Following call stacks
-- Checking variable usage
+### Current Project Code
+Use Grep/Read directly:
+- "Where is the authentication middleware in THIS project?"
+- "Show me OUR database models"
+- "Find all API endpoints WE defined"
 
-## Setup First: Add Important Dependencies
+### General Concepts
+Use training data (no tool needed):
+- "What is a closure in JavaScript?"
+- "Explain dependency injection"
+- "What is REST?"
 
-Before BK is useful, you need to add library sources:
+### Current Events
+Use web search:
+- "What's new in Next.js 15?"
+- "Latest release notes for TypeScript"
+- "Security advisory for npm packages"
 
+---
+
+## Setup: Index Your Dependencies
+
+BK only knows what you've indexed. Add your key dependencies:
+
+```bash
+# Get suggestions based on package.json
+/bluera-knowledge:suggest
+
+# Add important libraries
+/bluera-knowledge:add-repo https://github.com/expressjs/express
+/bluera-knowledge:add-repo https://github.com/honojs/hono
+
+# Index local docs
+/bluera-knowledge:add-folder ./docs --name=project-docs
+
+# Verify what's indexed
+/bluera-knowledge:stores
 ```
-/bk:suggest                  # Get recommendations
-/bk:add-repo <url> --name=<lib>   # Add important libs
-/bk:stores                   # Verify what's indexed
-```
+
+---
+
+## Quick Reference
+
+| Question Pattern | Use |
+|-----------------|-----|
+| "How does [library] work..." | BK |
+| "What does [library function] do..." | BK |
+| "What options/params does [library] accept..." | BK |
+| "What errors can [library] throw..." | BK |
+| "How should I use [library API]..." | BK |
+| "What changed in [library version]..." | BK |
+| "How do I integrate [library]..." | BK |
+| "Where is [thing] in OUR code..." | Grep/Read |
+| "What is [general concept]..." | Training data |
+| "What's new in [library] today..." | Web search |
+
+---
 
 ## Mental Model
 
 ```
-Current Project Files → Grep/Read directly
-           vs
-Library Sources (Vue, Pydantic, etc.) → BK (vector search OR Grep/Read)
+External Code (libraries, deps, specs)  →  Query BK
+Your Project Code                       →  Grep/Read directly
+General Knowledge                       →  Use training data
+Breaking News                           →  Web search
 ```
 
-BK gives you both ways to access library sources:
-1. Semantic search for discovery
-2. Grep/Read for precision
-
-Use whichever works best for your question!
+BK is cheap, fast, and authoritative. When in doubt about a library, query BK.