bluera-knowledge 0.31.0 → 0.33.0

package/skills/advanced-workflows/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: advanced-workflows
+description: Multi-tool orchestration patterns for BK operations
+---
+
+# 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/cancel/SKILL.md

@@ -0,0 +1,63 @@
+---
+description: Cancel a background job
+argument-hint: "[job-id]"
+allowed-tools: ["mcp__bluera-knowledge__execute"]
+---
+
+# Cancel Background Job
+
+Cancel a running or pending background job: **$ARGUMENTS**
+
+## Steps
+
+1. Parse the job ID from $ARGUMENTS (required)
+   - If no job ID provided, show error and suggest using /bluera-knowledge:check-status to list active jobs
+
+2. Use mcp__bluera-knowledge__execute tool with command "job:cancel":
+   - args.jobId: The job ID from $ARGUMENTS
+
+3. Display cancellation result:
+
+```
+✓ Job job_abc123def456 cancelled
+  Type: clone
+  Progress: 45% (was indexing)
+
+The job has been stopped and will not continue.
+```
+
+## When to Cancel
+
+Cancel a job when:
+- You accidentally started indexing the wrong repository
+- The operation is taking too long and you want to try a different approach
+- You need to free up system resources
+- You want to stop an operation before it completes
+
+## Important Notes
+
+- Only jobs in 'pending' or 'running' status can be cancelled
+- Completed or failed jobs cannot be cancelled
+- Cancelled jobs are marked with status 'cancelled' and remain in the job list
+- Partial work may be saved (e.g., partially indexed files remain in the database)
+
+## Error Handling
+
+If job cannot be cancelled:
+
+```
+✗ Cannot cancel job job_abc123def456: Job has already completed
+
+Only pending or running jobs can be cancelled.
+```
+
+If job not found:
+
+```
+✗ Job not found: job_abc123def456
+
+Common issues:
+- Check the job ID is correct
+- Use /bluera-knowledge:check-status to see all active jobs
+- Job may have already completed and been cleaned up
+```

package/skills/check-status/SKILL.md

@@ -0,0 +1,130 @@
+---
+description: Check status of background operations
+argument-hint: "[job-id]"
+allowed-tools: ["mcp__bluera-knowledge__execute"]
+---
+
+# Check Background Job Status
+
+Check the status of a background operation: **$ARGUMENTS**
+
+## Steps
+
+1. Parse $ARGUMENTS:
+   - If a job ID is provided, use it for specific job status
+   - If no arguments, show all active jobs
+
+2. If job ID provided:
+   - Use mcp__bluera-knowledge__execute tool with command "job:status":
+     - args.jobId: The job ID from $ARGUMENTS
+   - Display current status, progress, and details
+
+3. If no job ID provided:
+   - Use mcp__bluera-knowledge__execute tool with command "jobs":
+     - args.activeOnly: true
+   - Display a table of running/pending jobs
+
+## Display Format
+
+For a specific job:
+
+```
+Job Status: job_abc123def456
+───────────────────────────────────────
+Store:    react-query
+Phase:    indexing (2/2)
+Progress: █████░░░ 45% (562/1,247 files)
+Started:  2 minutes ago
+```
+
+For all active jobs, format as a rich table with progress bars:
+
+```
+Active Background Jobs
+────────────────────────────────────────────────────────────────────────────────────────────
+| Job ID             | Store            | Phase           | Progress     | Files          |
+|--------------------|------------------|-----------------|--------------|----------------|
+| job_3abaf9639770   | claude-agent-sdk | indexing (2/2)  | ██████░░ 59% | 32/77 files    |
+| job_4f0315fdcff9   | zustand          | cloning (1/2)   | █░░░░░░░ 15% | -              |
+| job_1d1d93fd254f   | uvicorn          | indexing (1/1)  | ████░░░░ 44% | 20/100 files   |
+| job_ac7584576f18   | tanstack-query   | crawling (1/2)  | ███░░░░░ 31% | 24 pages       |
+| job_8113ea07cf53   | framer-motion    | indexing (2/2)  | ███░░░░░ 30% | 8/1378 files   |
+| job_288c24b6724c   | monaco-editor    | indexing (1/1)  | ███░░░░░ 31% | 12/924 files   |
+
+✓ tiktoken: Completed
+
+6 jobs still running. The smaller repos (claude-agent-sdk, zustand, uvicorn) are progressing
+faster. The larger ones (tanstack-query: 1741 files, framer-motion: 1378 files,
+monaco-editor: 924 files) will take longer.
+```
+
+**Phase column:**
+- Read from `job.details.phase`, `job.details.phaseStep`, `job.details.phaseTotalSteps`
+- Format as: `{phase} ({step}/{total})` e.g., `indexing (2/2)`, `cloning (1/2)`
+- Phases: `cloning`, `crawling`, `indexing`
+- Clone jobs: cloning (1/2) → indexing (2/2)
+- Index jobs: indexing (1/1)
+- Crawl jobs: crawling (1/2) → indexing (2/2)
+
+**Progress bar rendering (8 chars wide):**
+
+Build the bar using these characters: `█` (filled) and `░` (empty)
+
+```
+Algorithm:
+  filled = Math.round(progress / 100 * 8)
+  bar = '█'.repeat(filled) + '░'.repeat(8 - filled) + ' ' + progress + '%'
+```
+
+Examples:
+```
+  0% → ░░░░░░░░ 0%
+ 15% → █░░░░░░░ 15%
+ 25% → ██░░░░░░ 25%
+ 31% → ███░░░░░ 31%
+ 44% → ████░░░░ 44%
+ 59% → █████░░░ 59%
+ 75% → ██████░░ 75%
+ 88% → ███████░ 88%
+100% → ████████ 100%
+```
+
+**Files column:**
+- For indexing: Show `{filesProcessed}/{totalFiles} files` from job.details
+- For crawling: Show `{pagesCrawled} pages` from job.details
+- For cloning (phase 1): Show `-` (no file count yet)
+
+**Summary section:**
+- After the table, add a brief summary noting:
+  - How many jobs are still running
+  - Which repos are progressing faster (smaller file counts)
+  - Which repos will take longer (larger file counts)
+- If any jobs recently completed, note them with ✓ prefix
+
+If no active jobs:
+
+```
+No active background jobs.
+
+Recent completed jobs:
+────────────────────────────────────────────────────────────────────────────────────────────
+| Job ID             | Store            | Phase           | Files          | Completed    |
+|--------------------|------------------|-----------------|----------------|--------------|
+| job_old123abc456   | react-query      | indexing (2/2)  | 245/245 files  | 5m ago       |
+| job_xyz789ghi012   | zustand          | indexing (1/1)  | 67/67 files    | 12m ago      |
+
+All jobs completed successfully.
+```
+
+## Error Handling
+
+If job not found:
+
+```
+✗ Job not found: job_abc123def456
+
+Common issues:
+- Check the job ID is correct
+- Job may have expired (stale pending jobs are marked failed after 2 hours)
+- Use /bluera-knowledge:check-status to see all active jobs
+```

package/skills/crawl/SKILL.md

@@ -0,0 +1,61 @@
+---
+description: Crawl web pages with natural language control and add to knowledge store
+argument-hint: "[url] [store-name] [--crawl instruction] [--extract instruction] [--fast]"
+allowed-tools: ["Bash(node ${CLAUDE_PLUGIN_ROOT}/dist/index.js crawl:*)"]
+context: fork
+---
+
+**⚠️ IMPORTANT: Store name is a POSITIONAL argument, NOT an option!**
+
+```
+WRONG: crawl https://example.com --store=my-store
+RIGHT: crawl https://example.com my-store
+```
+
+Crawling and indexing: $ARGUMENTS
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/dist/index.js crawl $ARGUMENTS
+```
+
+The web pages will be crawled with intelligent link selection and optional natural language extraction, then indexed for searching.
+
+**Note:** The web store is auto-created if it doesn't exist. No need to create the store first.
+
+## Usage Examples
+
+**Intelligent crawl strategy:**
+```
+/bluera-knowledge:crawl https://code.claude.com/docs/en/ claude-docs --crawl "all Getting Started pages"
+```
+
+**With extraction:**
+```
+/bluera-knowledge:crawl https://example.com/pricing pricing-store --extract "extract pricing and features"
+```
+
+**Both strategy and extraction:**
+```
+/bluera-knowledge:crawl https://docs.example.com my-docs --crawl "API reference pages" --extract "API endpoints and parameters"
+```
+
+**Simple BFS mode:**
+```
+/bluera-knowledge:crawl https://example.com/docs docs-store --simple
+```
+
+**Fast mode (axios-only, no JavaScript rendering):**
+```
+/bluera-knowledge:crawl https://example.com/docs docs-store --fast --max-pages 20
+```
+
+## Options
+
+- `--crawl <instruction>` - Natural language instruction for which pages to crawl (e.g., "all Getting Started pages")
+- `--extract <instruction>` - Natural language instruction for what content to extract (e.g., "extract API references")
+- `--simple` - Use simple BFS (breadth-first search) mode instead of intelligent crawling
+- `--max-pages <number>` - Maximum number of pages to crawl (default: 50)
+- `--fast` - Use fast axios-only mode instead of headless browser
+  - Default behavior uses headless browser (Playwright via crawl4ai) for JavaScript-rendered sites
+  - Use `--fast` when the target site doesn't use client-side rendering
+  - Much faster than headless mode but may miss content from JavaScript-heavy sites

package/skills/doctor/SKILL.md

@@ -0,0 +1,27 @@
+---
+description: Diagnose plugin issues and get fix instructions
+allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT:-.}/scripts/doctor.sh)"]
+---
+# Bluera Knowledge Doctor
+
+Run comprehensive diagnostics to identify and fix plugin issues.
+
+## Instructions
+
+Run the doctor script to check all prerequisites:
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT:-.}/scripts/doctor.sh"
+```
+
+The script checks:
+1. **Build tools** (make/gcc) - Required for native modules
+2. **Node.js** - Required for MCP server
+3. **Plugin dependencies** (node_modules) - Required for MCP server
+4. **MCP wrapper** - Required for MCP server startup
+5. **Python 3** - Optional, for embeddings
+6. **Playwright** - Optional, for web crawling
+
+For any `[FAIL]` items, follow the FIX instructions provided.
+
+After fixing issues, restart Claude Code for changes to take effect.