bluera-knowledge 0.30.0 → 0.32.0

package/skills/knowledge-search/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: knowledge-search
+description: Query BK for library internals via vector search or direct Grep/Read
+---
+
+# Using Bluera Knowledge (BK)
+
+BK provides access to **definitive library sources** for your project dependencies.
+
+## The Rule: Query BK for External Code
+
+**Any question about libraries, dependencies, or indexed reference material should query BK.**
+
+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 (Discovery)
+Find concepts and patterns across indexed content:
+```
+search("vue reactivity system")
+/bluera-knowledge:search "pydantic custom validators"
+```
+
+### 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! Use vector search for discovery, Grep/Read for specific functions.
+
+## 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
+
+User: "How does Vue's computed properties work internally?"
+
+Claude:
+1. Check stores: `list_stores` MCP tool → vue store exists
+2. Vector search: `search("vue computed properties")` → finds computed.ts
+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/search-optimization/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: search-optimization
+description: Optimize BK search with intent, detail level, and store filtering
+---
+
+# Optimizing Bluera Knowledge Search
+
+Master the `search()` MCP tool parameters to get better results with less context usage.
+
+## Understanding Search Parameters
+
+```typescript
+search(
+  query: string,                    // Your search query
+  intent?: SearchIntent,            // What you're looking for
+  detail?: 'minimal' | 'contextual' | 'full',  // How much context to return
+  limit?: number,                   // Max results (default: 10)
+  stores?: string[]                 // Which stores to search
+)
+```
+
+## Search Intent: Choosing the Right Type
+
+The `intent` parameter helps the search engine rank results appropriately for your query type.
+
+### Intent Decision Tree
+
+**Looking for implementation details? Use `find-implementation`**
+- "How does X work internally?"
+- "Show me the implementation of Y"
+- "What's inside the Z class/function?"
+
+```
+search("Vue computed properties implementation", intent='find-implementation')
+→ Prioritizes: actual class/function implementations
+→ Ranks higher: ComputedRefImpl class, createComputed() function
+→ Ranks lower: tests, documentation, examples
+```
+
+**Looking for usage patterns? Use `find-pattern`**
+- "How to use X?"
+- "Examples of Y pattern"
+- "Common ways to implement Z"
+
+```
+search("React hooks patterns", intent='find-pattern')
+→ Prioritizes: example code, usage patterns, HOCs
+→ Ranks higher: common patterns like useEffect cleanup
+→ Ranks lower: internal implementation details
+```
+
+**Looking for references? Use `find-usage`**
+- "Where is X used?"
+- "Find all calls to Y"
+- "What depends on Z?"
+
+```
+search("useCallback usage", intent='find-usage')
+→ Prioritizes: call sites, import statements
+→ Ranks higher: files importing and using useCallback
+→ Ranks lower: useCallback's own implementation
+```
+
+**Looking for definitions/APIs? Use `find-definition`**
+- "What is the API for X?"
+- "Show me the type definition of Y"
+- "What are the parameters for Z?"
+
+```
+search("FastAPI route decorator", intent='find-definition')
+→ Prioritizes: function signatures, type definitions
+→ Ranks higher: @app.get() decorator definition
+→ Ranks lower: examples using the decorator
+```
+
+**Looking for documentation? Use `find-documentation`**
+- "What does the doc say about X?"
+- "Explain Y from the documentation"
+- "API reference for Z"
+
+```
+search("Pydantic validators documentation", intent='find-documentation')
+→ Prioritizes: README, docstrings, comments
+→ Ranks higher: markdown docs, inline documentation
+→ Ranks lower: implementation code
+```
+
+### Default (No Intent)
+
+If unsure, omit `intent` - the search engine will use hybrid ranking:
+
+```
+search("authentication middleware")
+→ Returns mixed: implementations, patterns, usage, docs
+→ Balanced ranking across all categories
+```
+
+## Detail Level: Progressive Context Strategy
+
+The `detail` parameter controls how much code context is returned **per result**.
+
+### Detail Levels Explained
+
+| Level | What You Get | Tokens/Result | Use When |
+|-------|--------------|---------------|----------|
+| `minimal` | Summary, file path, relevance | ~100 | Browsing many results |
+| `contextual` | + imports, types, signatures | ~300 | Need interface context |
+| `full` | + complete code, all context | ~800 | Deep dive on specific file |
+
+### Progressive Detail Strategy (Recommended)
+
+**Step 1: Start Minimal**
+```
+search(query, detail='minimal', limit=20)
+→ Get 20 summaries (~2k tokens total)
+→ Scan quickly for relevance
+→ Identify top 3-5 candidates
+```
+
+**Step 2: Evaluate Scores**
+```
+Review relevance scores:
+- 0.9-1.0: Excellent match (almost certainly relevant)
+- 0.7-0.9: Strong match (very likely relevant)
+- 0.5-0.7: Moderate match (possibly relevant)
+- < 0.5: Weak match (probably not relevant)
+```
+
+**Step 3: Selective Deep Dive**
+```
+For top results (score > 0.7):
+  get_full_context(result_ids)
+  → Fetch complete code only for relevant items
+
+For moderate results (score 0.5-0.7):
+  search(refined_query, detail='contextual')
+  → Try different query with more context
+```
+
+## Result Limiting
+
+The `limit` parameter caps the number of results returned.
+
+### Choosing the Right Limit
+
+| Limit | Mode | Use When |
+|-------|------|----------|
+| 20-50 | Discovery | Exploring, not sure what exists |
+| 10-20 | Standard | Specific question, multiple files |
+| 3-5 | Targeted | Know exactly what you need |
+
+**Tip**: Large limits work best with `detail='minimal'` to control tokens.
+
+## Store Filtering
+
+The `stores` parameter restricts search to specific knowledge stores.
+
+### When to Filter Stores
+
+**✅ Filter when:** You know the library, comparing specific libs, want focused results
+
+**❌ Don't filter when:** Discovering where code lives, want cross-library perspective
+
+```
+# Check available stores first
+list_stores()
+
+# Then filter
+search(query, stores=['fastapi', 'express'])
+```
+
+## Quick Reference
+
+### High-Efficiency Defaults
+```
+search(query, detail='minimal', limit=20)
+→ Good for most discovery tasks
+→ Review, then selectively fetch full context
+```
+
+### High-Precision Defaults
+```
+search(query, intent='find-implementation', detail='full', limit=5, stores=['known-lib'])
+→ When you know exactly what you're looking for
+→ Fastest path to deep answer
+```
+
+### Balanced Defaults
+```
+search(query, detail='contextual', limit=10)
+→ Good middle ground
+→ See interfaces without full implementation
+```
+
+## Deep Dive
+
+For advanced strategies and token optimization examples:
+- @references/strategies.md - Combined optimization strategies with token counts
+- @references/mistakes.md - Common mistakes to avoid

package/skills/search-optimization/references/mistakes.md

@@ -0,0 +1,21 @@
+# Common Mistakes to Avoid
+
+1. **Using detail='full' with limit=50**
+   - Result: ~40k tokens consumed
+   - Fix: Start with detail='minimal', escalate selectively
+
+2. **Not using intent parameter**
+   - Result: Mixed ranking, less relevant results
+   - Fix: Choose intent based on query type
+
+3. **Over-filtering stores too early**
+   - Result: Miss better answers in other libraries
+   - Fix: Search broadly first, then narrow
+
+4. **Setting limit too low (1-2)**
+   - Result: Miss relevant alternatives
+   - Fix: Use limit=5 minimum, more for discovery
+
+5. **Not checking relevance scores**
+   - Result: Waste time on low-relevance results
+   - Fix: Filter by score > 0.7 before deep dive

package/skills/search-optimization/references/strategies.md

@@ -0,0 +1,80 @@
+# Combined Optimization Strategies
+
+### Strategy 1: Efficient Discovery
+```
+Goal: Find something across many files, minimize tokens
+
+1. search(query, detail='minimal', limit=30)
+   → Browse summaries (~3k tokens)
+
+2. Filter top 5 by score (>0.7)
+
+3. get_full_context(top_5_ids)
+   → Deep dive selectively (~4k tokens)
+
+Total: ~7k tokens (vs ~24k with detail='full' upfront)
+Savings: ~70% token reduction
+```
+
+### Strategy 2: Precise Targeting
+```
+Goal: Get exactly what you need, fast
+
+1. Identify store: list_stores()
+
+2. search(precise_query,
+         intent='find-implementation',
+         detail='full',
+         limit=3,
+         stores=['target-store'])
+   → Exact match with full code
+
+Total: ~2.5k tokens
+Result: Fastest path to answer
+```
+
+### Strategy 3: Comparative Analysis
+```
+Goal: Compare implementations across libraries
+
+1. search(query,
+         intent='find-implementation',
+         detail='minimal',
+         limit=20,
+         stores=['lib1', 'lib2', 'lib3'])
+   → Get summaries from multiple libraries
+
+2. Review distribution:
+   - lib1: 8 results
+   - lib2: 7 results
+   - lib3: 5 results
+
+3. get_full_context(top_2_from_each_lib)
+   → Compare implementations
+
+Total: ~5k tokens
+Result: Balanced cross-library comparison
+```
+
+---
+
+# Token Usage Examples
+
+Real token counts for different strategies:
+
+```
+# Inefficient approach
+search("auth middleware", detail='full', limit=30)
+→ 30 results × 800 tokens = 24,000 tokens
+→ Most results not even relevant!
+
+# Optimized approach
+search("auth middleware", detail='minimal', limit=30)
+→ 30 results × 100 tokens = 3,000 tokens
+→ Identify top 3 (score > 0.8)
+
+get_full_context([id1, id2, id3])
+→ 3 results × 800 tokens = 2,400 tokens
+
+Total: 5,400 tokens (78% reduction!)
+```