bluera-knowledge 0.16.5 → 0.17.0

package/hooks/skill-rules.json

@@ -1,122 +0,0 @@
-{
-  "description": "bluera-knowledge skill activation rules - technology-agnostic patterns for development scenarios",
-  "version": 2,
-  "globalExclusions": [
-    { "keyword": "bluera-knowledge" },
-    { "keyword": "bluera knowledge" },
-    { "keyword": "/bluera-knowledge:" },
-    { "regex": "mcp__.*bluera" }
-  ],
-  "threshold": 2,
-  "skills": [
-    {
-      "name": "knowledge-search",
-      "description": "How to query Bluera Knowledge for library/dependency questions",
-      "triggers": [
-        { "regex": "the\\s+\\w+(-\\w+)*\\s+(package|library|module|framework|dependency)", "weight": 3 },
-        { "regex": "\\w+(-\\w+)*\\s+(package|library|module)\\s+(is|does|keeps|isn't|won't|doesn't)", "weight": 3 },
-        { "regex": "\\w+(-\\w+)*\\s+(documentation|docs)\\b", "weight": 2 },
-        { "regex": "error\\s+(from|in|with)\\s+(the\\s+)?\\w+(-\\w+)*\\s+(package|library|module)", "weight": 3 },
-        { "regex": "(package|library|dependency|module)\\s+(is\\s+)?(throwing|throws|error|failing)", "weight": 3 },
-        { "regex": "how\\s+does\\s+(the\\s+)?\\w+(-\\w+)*\\s+(package|library|module|framework)\\s+(handle|work|process)", "weight": 3 },
-        { "regex": "what\\s+does\\s+(the\\s+)?\\w+(-\\w+)*\\s+(package|library)\\s+(do|return|accept)", "weight": 3 },
-        { "regex": "why\\s+does\\s+(the\\s+)?\\w+(-\\w+)*\\s+(package|library|module)", "weight": 3 },
-        { "regex": "(configure|config|settings)\\s+(for\\s+)?(the\\s+)?\\w+(-\\w+)*\\s+(package|library)", "weight": 3 },
-        { "regex": "(upgraded?|updated?)\\s+(the\\s+)?\\w+(-\\w+)*\\s+(package|library|dependency)", "weight": 2 },
-        { "regex": "integrate\\s+(the\\s+)?\\w+(-\\w+)*\\s+(package|library)", "weight": 2 },
-        { "regex": "dependency\\s+(is|keeps|isn't|won't|error|issue|problem)", "weight": 2 },
-        { "regex": "third[- ]party\\s+(library|package|code)", "weight": 2 }
-      ],
-      "exclusions": [
-        { "keyword": "my code" },
-        { "keyword": "our code" },
-        { "keyword": "this function" },
-        { "keyword": "this file" },
-        { "keyword": "this component" },
-        { "keyword": "this class" },
-        { "keyword": "this project" },
-        { "keyword": "I wrote" },
-        { "keyword": "we wrote" },
-        { "keyword": "my implementation" },
-        { "keyword": "store" },
-        { "keyword": "index" }
-      ]
-    },
-    {
-      "name": "when-to-query",
-      "description": "Decision guide for Bluera Knowledge vs Grep/Read",
-      "triggers": [
-        { "keyword": "should i grep", "weight": 2 },
-        { "keyword": "where should i look", "weight": 2 },
-        { "keyword": "grep or search", "weight": 2 },
-        { "keyword": "search or grep", "weight": 2 },
-        { "regex": "where\\s+(should|do)\\s+i\\s+(find|look)\\s+.*(library|package|dependency)", "weight": 3 },
-        { "regex": "is\\s+there\\s+a\\s+better\\s+way\\s+to\\s+(search|find)", "weight": 2 },
-        { "regex": "should\\s+i\\s+(use\\s+)?grep\\s+(for|to)", "weight": 2 },
-        { "regex": "how\\s+(do|should)\\s+i\\s+find.*(in|from)\\s+(a\\s+)?(library|package|dependency)", "weight": 3 }
-      ],
-      "exclusions": [
-        { "keyword": "store" },
-        { "keyword": "index" }
-      ]
-    },
-    {
-      "name": "search-optimization",
-      "description": "Optimizing search parameters and token usage",
-      "triggers": [
-        { "keyword": "too many results", "weight": 2 },
-        { "keyword": "too few results", "weight": 2 },
-        { "keyword": "limit results", "weight": 2 },
-        { "keyword": "reduce tokens", "weight": 2 },
-        { "keyword": "token usage", "weight": 2 },
-        { "keyword": "optimize search", "weight": 2 },
-        { "keyword": "detail level", "weight": 2 },
-        { "regex": "\\b(minimal|contextual|full)\\s+detail", "weight": 2 },
-        { "regex": "\\b(vector|fts|hybrid)\\s+(search|mode)", "weight": 2 },
-        { "regex": "narrow\\s+(down\\s+)?(the\\s+)?results", "weight": 2 },
-        { "regex": "search\\s+(is\\s+)?(returning|giving)\\s+(too\\s+)?(many|few)", "weight": 2 }
-      ],
-      "exclusions": [
-        { "regex": "--?(limit|detail|mode|threshold)\\s*=" }
-      ]
-    },
-    {
-      "name": "advanced-workflows",
-      "description": "Multi-tool orchestration patterns",
-      "triggers": [
-        { "keyword": "multi-step", "weight": 2 },
-        { "keyword": "orchestration", "weight": 2 },
-        { "keyword": "job monitoring", "weight": 2 },
-        { "keyword": "background job", "weight": 2 },
-        { "keyword": "combine tools", "weight": 2 },
-        { "keyword": "chain operations", "weight": 2 },
-        { "regex": "chain.*searches", "weight": 2 },
-        { "regex": "multiple.*searches", "weight": 2 },
-        { "regex": "search.*then\\s+(summarize|extract|filter)", "weight": 2 },
-        { "regex": "for\\s+each\\s+(search\\s+)?(result|match)", "weight": 2 }
-      ],
-      "exclusions": []
-    },
-    {
-      "name": "store-lifecycle",
-      "description": "Managing knowledge stores",
-      "triggers": [
-        { "keyword": "add store", "weight": 2 },
-        { "keyword": "create store", "weight": 2 },
-        { "keyword": "delete store", "weight": 2 },
-        { "keyword": "remove store", "weight": 2 },
-        { "keyword": "index store", "weight": 2 },
-        { "keyword": "re-index", "weight": 2 },
-        { "keyword": "reindex", "weight": 2 },
-        { "keyword": "knowledge store", "weight": 2 },
-        { "regex": "add\\s+(a\\s+)?(repo|repository|folder|directory)\\s+(to|for)\\s+(knowledge|indexing|search)", "weight": 3 },
-        { "regex": "index\\s+(a|the|my)\\s+(repo|repository|folder|directory|library|package)", "weight": 2 },
-        { "regex": "set\\s+up.*(knowledge|search)\\s*(store|index)", "weight": 2 },
-        { "regex": "(backup|snapshot|archive).*(knowledge|search)\\s*(store|index)", "weight": 2 }
-      ],
-      "exclusions": [
-        { "regex": "/bluera-knowledge:(add-repo|add-folder|remove-store|index)" }
-      ]
-    }
-  ]
-}

package/skills/advanced-workflows/SKILL.md

@@ -1,273 +0,0 @@
----
-name: advanced-workflows
-description: Multi-tool orchestration patterns for complex Bluera Knowledge operations. Teaches progressive library exploration, adding libraries with job monitoring, handling large result sets, multi-store searches, and error recovery workflows.
----
-
-# Advanced Bluera Knowledge Workflows
-
-Master complex multi-tool operations that combine multiple MCP tools for efficient knowledge retrieval and management.
-
-## Progressive Library Exploration
-
-When exploring a new library or codebase, use this pattern for efficient discovery:
-
-### Workflow: Find Relevant Code in Unknown Library
-
-```
-1. list_stores()
-   → See what's indexed, identify target store
-
-2. get_store_info(store)
-   → Get metadata: file paths, size, indexed files
-   → Understand scope before searching
-
-3. search(query, detail='minimal', stores=[target])
-   → Get high-level summaries of relevant code
-   → Review relevance scores (>0.7 = good match)
-
-4. get_full_context(result_ids[top_3])
-   → Deep dive on most relevant results only
-   → Get complete code with full context
-```
-
-**Example:**
-
-User: "How does Vue's computed properties work?"
-
-```
-list_stores()
-→ Found: vue, react, pydantic
-
-get_store_info('vue')
-→ Path: .bluera/bluera-knowledge/repos/vue/
-→ Files: 2,847 indexed
-
-search("computed properties", intent='find-implementation', detail='minimal', stores=['vue'])
-→ Result 1: packages/reactivity/src/computed.ts (score: 0.92)
-→ Result 2: packages/reactivity/__tests__/computed.spec.ts (score: 0.85)
-→ Result 3: packages/runtime-core/src/apiComputed.ts (score: 0.78)
-
-get_full_context(['result_1_id', 'result_2_id'])
-→ Full code for ComputedRefImpl class
-→ Complete API implementation
-
-Now explain with authoritative source code.
-```
-
-## Adding New Library with Job Monitoring
-
-When adding large libraries, monitor indexing progress to know when search is ready:
-
-### Workflow: Add Library and Wait for Index
-
-```
-1. create_store(url_or_path, name)
-   → Returns: job_id
-   → Background indexing starts
-
-2. check_job_status(job_id)
-   → Poll every 10-30 seconds
-   → Status: 'pending' | 'running' | 'completed' | 'failed'
-   → Progress: percentage, current file
-
-3. When status='completed':
-   list_stores()
-   → Verify store appears in list
-
-4. search(query, stores=[new_store], limit=5)
-   → Test search works
-   → Verify indexing quality
-```
-
-**Example:**
-
-```
-create_store('https://github.com/fastapi/fastapi', 'fastapi')
-→ job_id: 'job_abc123'
-→ Status: Indexing started in background
-
-# Poll for completion (typically 30-120 seconds for medium repos)
-check_job_status('job_abc123')
-→ Status: running
-→ Progress: 45% (processing src/fastapi/routing.py)
-
-# ... wait 30 seconds ...
-
-check_job_status('job_abc123')
-→ Status: completed
-→ Indexed: 487 files, 125k lines
-
-# Verify and test
-list_stores()
-→ fastapi: 487 files, vector + FTS indexed
-
-search("dependency injection", stores=['fastapi'], limit=3)
-→ Returns relevant FastAPI DI patterns
-→ Store is ready for use!
-```
-
-## Handling Large Result Sets
-
-When initial search returns many results, use progressive detail to avoid context overload:
-
-### Workflow: Progressive Detail Strategy
-
-```
-1. search(query, detail='minimal', limit=20)
-   → Get summaries only (~100 tokens/result)
-   → Review all 20 summaries quickly
-
-2. Filter by relevance score:
-   - Score > 0.8: Excellent match
-   - Score 0.6-0.8: Good match
-   - Score < 0.6: Possibly irrelevant
-
-3. For top 3-5 results (score > 0.7):
-   get_full_context(selected_ids)
-   → Fetch complete code only for relevant items
-   → Saves ~80% context vs fetching all upfront
-
-4. If nothing relevant:
-   search(refined_query, detail='contextual', limit=10)
-   → Try different query with more context
-   → Or broaden/narrow the search
-```
-
-**Example:**
-
-```
-# Initial broad search
-search("authentication middleware", detail='minimal', limit=20)
-→ 20 results, scores ranging 0.45-0.92
-→ Total context: ~2k tokens (minimal)
-
-# Filter by score
-Top results (>0.7):
-  - Result 3: auth/jwt.ts (score: 0.92)
-  - Result 7: middleware/authenticate.ts (score: 0.85)
-  - Result 12: auth/session.ts (score: 0.74)
-
-# Get full code for top 3 only
-get_full_context(['result_3', 'result_7', 'result_12'])
-→ Complete implementations for relevant files only
-→ Context: ~3k tokens (vs ~15k if we fetched all 20)
-
-# Found what we needed! If not, would refine query and retry.
-```
-
-## Multi-Store Search with Ranking
-
-When searching across multiple stores, use ranking to prioritize results:
-
-### Workflow: Cross-Library Search
-
-```
-1. search(query, limit=10)
-   → Searches ALL stores
-   → Returns mixed results ranked by relevance
-
-2. Review store distribution:
-   - If dominated by one store: might narrow to specific stores
-   - If balanced: good cross-library perspective
-
-3. For specific library focus:
-   search(query, stores=['lib1', 'lib2'], limit=15)
-   → Search only relevant libraries
-   → Get more results from target libraries
-```
-
-**Example:**
-
-User: "How do different frameworks handle routing?"
-
-```
-# Search all indexed frameworks
-search("routing implementation", intent='find-implementation', limit=15)
-→ Result mix:
-  - express (score: 0.91)
-  - fastapi (score: 0.89)
-  - hono (score: 0.87)
-  - vue-router (score: 0.82)
-  - ...
-
-# All stores represented, good comparative view!
-
-# If user wants deeper FastAPI focus:
-search("routing implementation", stores=['fastapi', 'starlette'], limit=20)
-→ More FastAPI/Starlette-specific results
-→ Deeper exploration of Python framework routing
-```
-
-## Error Recovery
-
-When operations fail, use these recovery patterns:
-
-### Workflow: Handle Indexing Failures
-
-```
-1. create_store() fails or job_status shows 'failed'
-   → Check error message
-   → Common issues:
-     - Git auth required (private repo)
-     - Invalid URL/path
-     - Disk space
-     - Network timeout
-
-2. Recovery actions:
-   - Auth issue: Provide credentials or use HTTPS
-   - Invalid path: Verify URL/path exists
-   - Disk space: delete_store() unused stores
-   - Network: Retry with smaller repo or use --shallow
-
-3. Verify recovery:
-   list_stores() → Check store appeared
-   search(test_query, stores=[new_store]) → Verify searchable
-```
-
-**Example:**
-
-```
-create_store('https://github.com/private/repo', 'my-repo')
-→ job_id: 'job_xyz'
-
-check_job_status('job_xyz')
-→ Status: failed
-→ Error: "Authentication required for private repository"
-
-# Recovery: Use authenticated URL or SSH
-create_store('git@github.com:private/repo.git', 'my-repo')
-→ job_id: 'job_xyz2'
-
-check_job_status('job_xyz2')
-→ Status: completed
-→ Success!
-```
-
-## Combining Workflows
-
-Real-world usage often combines these patterns:
-
-```
-User: "I need to understand how Express and Hono handle middleware differently"
-
-1. list_stores() → check if both indexed
-2. If not: create_store() for missing framework(s)
-3. check_job_status() → wait for indexing
-4. search("middleware implementation", stores=['express', 'hono'], detail='minimal')
-5. Review summaries, identify key files
-6. get_full_context() for 2-3 most relevant from each framework
-7. Compare implementations with full context
-```
-
-This multi-step workflow is efficient, targeted, and conserves context.
-
-## Best Practices
-
-1. **Always start with detail='minimal'** - Get summaries first, full context selectively
-2. **Monitor background jobs** - Don't search newly added stores until indexing completes
-3. **Use intent parameter** - Helps ranking ('find-implementation' vs 'find-pattern' vs 'find-usage')
-4. **Filter by stores when known** - Faster, more focused results
-5. **Check relevance scores** - >0.7 is usually a strong match, <0.5 might be noise
-6. **Progressive refinement** - Broad search → filter → narrow → full context
-
-These workflows reduce token usage, minimize tool calls, and get you to the right answer faster.

package/skills/knowledge-search/SKILL.md

@@ -1,110 +0,0 @@
----
-name: knowledge-search
-description: Teaches how to use Bluera Knowledge for accessing library sources and reference material. Explains two approaches - vector search via MCP/slash commands for discovery, or direct Grep/Read access to cloned repos for precision. Shows when to use each method and example workflows for querying library internals.
----
-
-# 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.