bluera-knowledge 0.9.21

package/commands/add-folder.md

@@ -0,0 +1,48 @@
+---
+description: Index a local folder of reference material
+argument-hint: "[path] [--name store-name]"
+allowed-tools: ["mcp__bluera-knowledge__execute"]
+---
+
+# Add Local Folder to Knowledge Stores
+
+Index a local folder of reference material: **$ARGUMENTS**
+
+## Steps
+
+1. Parse arguments from $ARGUMENTS:
+   - Extract the folder path (required, first positional argument)
+   - Extract --name parameter (optional, defaults to folder name)
+
+2. Use mcp__bluera-knowledge__execute tool with command "store:create":
+   - args.name: Store name (from --name or folder basename)
+   - args.type: "file"
+   - args.source: The folder path
+
+3. Display results showing job ID for background indexing:
+
+```
+✓ Adding folder: /Users/me/my-docs...
+✓ Created store: my-docs (e5f6g7h8...)
+  Location: ~/.local/share/bluera-knowledge/stores/e5f6g7h8.../
+
+🔄 Indexing started in background
+   Job ID: job_xyz789abc123
+
+Check status with: /bluera-knowledge:check-status job_xyz789abc123
+Or view all jobs: /bluera-knowledge:check-status
+```
+
+## Error Handling
+
+If creation fails (e.g., path doesn't exist, permission denied):
+
+```
+✗ Failed to add folder: [error message]
+
+Common issues:
+- Check that the path exists
+- Ensure you have read permissions for the folder
+- Verify the path is a directory, not a file
+- Use absolute paths to avoid ambiguity
+```

package/commands/add-repo.md

@@ -0,0 +1,50 @@
+---
+description: Clone and index a library source repository
+argument-hint: "[git-url] [--name store-name] [--branch branch-name]"
+allowed-tools: ["mcp__bluera-knowledge__execute"]
+---
+
+# Add Repository to Knowledge Stores
+
+Clone and index a library source repository: **$ARGUMENTS**
+
+## Steps
+
+1. Parse arguments from $ARGUMENTS:
+   - Extract the git URL (required, first positional argument)
+   - Extract --name parameter (optional, defaults to repo name from URL)
+   - Extract --branch parameter (optional, defaults to default branch)
+
+2. Use mcp__bluera-knowledge__execute tool with command "store:create":
+   - args.name: Store name (from --name or extracted from URL)
+   - args.type: "repo"
+   - args.source: The git URL
+   - args.branch: Branch name (if --branch specified)
+
+3. Display results showing job ID for background indexing:
+
+```
+✓ Cloning https://github.com/facebook/react...
+✓ Created store: react (a1b2c3d4...)
+  Location: ~/.local/share/bluera-knowledge/stores/a1b2c3d4.../
+
+🔄 Indexing started in background
+   Job ID: job_abc123def456
+
+Check status with: /bluera-knowledge:check-status job_abc123def456
+Or view all jobs: /bluera-knowledge:check-status
+```
+
+## Error Handling
+
+If creation fails (e.g., invalid URL, network error, git not available):
+
+```
+✗ Failed to clone repository: [error message]
+
+Common issues:
+- Check that the git URL is valid and accessible
+- Ensure you have network connectivity
+- Verify git is installed on your system
+- For private repos, check your SSH keys or credentials
+```

package/commands/cancel.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/commands/check-status.md

@@ -0,0 +1,78 @@
+---
+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
+───────────────────────────────────────
+Type:     clone
+Status:   running
+Progress: ███████████░░░░░░░░░ 45%
+Message:  Indexed 562/1,247 files
+Started:  2 minutes ago
+```
+
+For all active jobs:
+
+```
+Active Background Jobs
+───────────────────────────────────────────────────────────────
+| Job ID            | Type  | Status  | Progress | Started  |
+|-------------------|-------|---------|----------|----------|
+| job_abc123def456  | clone | running | 45%      | 2m ago   |
+| job_xyz789ghi012  | index | pending | 0%       | Just now |
+
+Use /bluera-knowledge:check-status <job-id> for details
+```
+
+If no active jobs:
+
+```
+No active background jobs.
+
+Recent completed jobs:
+| Job ID            | Type  | Status    | Completed |
+|-------------------|-------|-----------|-----------|
+| job_old123abc456  | clone | completed | 5m ago    |
+
+Use /bluera-knowledge:cancel <job-id> to cancel a running job
+```
+
+## Error Handling
+
+If job not found:
+
+```
+✗ Job not found: job_abc123def456
+
+Common issues:
+- Check the job ID is correct
+- Job may have been cleaned up (completed jobs are removed after 24 hours)
+- Use /bluera-knowledge:check-status to see all active jobs
+```

package/commands/crawl.md

@@ -0,0 +1,51 @@
+---
+description: Crawl web pages with natural language control and add to knowledge store
+argument-hint: "[url] [store-name] [--crawl instruction] [--extract instruction]"
+allowed-tools: [Bash(*)]
+---
+
+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.
+
+## 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
+```
+
+**Headless browser for JavaScript-rendered sites:**
+```
+/bluera-knowledge:crawl https://code.claude.com/docs claude-docs --headless --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)
+- `--headless` - Use headless browser (Playwright via crawl4ai) for JavaScript-rendered sites
+  - Required for modern frameworks (Next.js, React, Vue, etc.) that render content via client-side JavaScript
+  - Slower than default (axios) but handles client-side rendering
+  - Falls back to axios if headless fetch fails

package/commands/index.md

@@ -0,0 +1,48 @@
+---
+description: Re-index a knowledge store
+argument-hint: "[store-name-or-id]"
+allowed-tools: ["mcp__bluera-knowledge__execute"]
+---
+
+# Re-index Knowledge Store
+
+Re-index a knowledge store: **$ARGUMENTS**
+
+## Steps
+
+1. Parse the store name or ID from $ARGUMENTS (required)
+
+2. Use mcp__bluera-knowledge__execute tool with command "store:index":
+   - args.store: The store name or ID from $ARGUMENTS
+
+3. Display results showing job ID for background indexing:
+
+```
+✓ Indexing store: react...
+🔄 Indexing started in background
+   Job ID: job_def456ghi789
+
+Check status with: /bluera-knowledge:check-status job_def456ghi789
+Or view all jobs: /bluera-knowledge:check-status
+```
+
+## When to Re-index
+
+Re-index a store when:
+- The source repository has been updated (for repo stores)
+- Files have been added or modified (for file stores)
+- You want to refresh embeddings with an updated model
+- Search results seem out of date
+
+## Error Handling
+
+If indexing fails:
+
+```
+✗ Failed to index store: [error message]
+
+Common issues:
+- Store name or ID not found - use /bluera-knowledge:stores to list available stores
+- Source directory no longer exists (for file stores)
+- Network issues pulling latest changes (for repo stores)
+```

package/commands/remove-store.md

@@ -0,0 +1,52 @@
+---
+description: Delete a knowledge store and all associated data
+argument-hint: "[store-name-or-id]"
+allowed-tools: ["mcp__bluera-knowledge__execute"]
+---
+
+# Remove Knowledge Store
+
+Delete a knowledge store and all associated data: **$ARGUMENTS**
+
+## Steps
+
+1. Parse the store name or ID from $ARGUMENTS (required)
+   - If no store provided, show error and suggest using /bluera-knowledge:stores to list available stores
+
+2. Use mcp__bluera-knowledge__execute tool with command "store:delete":
+   - args.store: The store name or ID from $ARGUMENTS
+
+3. Display deletion result:
+
+```
+Store "react" deleted successfully.
+
+Removed:
+- Store registry entry
+- LanceDB search index
+- Cloned repository files (for repo stores)
+```
+
+## What Gets Deleted
+
+When you remove a store:
+- **Registry entry** - Store is removed from the list
+- **Search index** - LanceDB vector embeddings are dropped
+- **Cloned files** - For repo stores created from URLs, the cloned repository is deleted
+
+## Warning
+
+This action is **permanent**. The store and all indexed data will be deleted.
+To re-create, you'll need to add and re-index the source again.
+
+## Error Handling
+
+If store not found:
+
+```
+Store not found: nonexistent-store
+
+Available stores:
+- Use /bluera-knowledge:stores to list all stores
+- Check spelling of store name or ID
+```

package/commands/search.md

@@ -0,0 +1,79 @@
+---
+description: Search indexed library sources
+argument-hint: "[query] [--stores names] [--limit N]"
+allowed-tools: ["mcp__bluera-knowledge__search"]
+---
+
+# Search Knowledge Stores
+
+Search indexed library sources for: **$ARGUMENTS**
+
+## Steps
+
+1. Parse the query from $ARGUMENTS:
+   - Extract the search query (required)
+   - Extract --stores parameter (optional, comma-separated store names)
+   - Extract --limit parameter (optional, default 10)
+
+2. Call mcp__bluera-knowledge__search with:
+   - query: The search query string
+   - stores: Array of store names (if --stores specified)
+   - limit: Number of results (if --limit specified, default 10)
+   - detail: "contextual"
+   - intent: "find-implementation"
+
+3. Format and display results with rich context:
+
+   ```
+   ## Search Results: "query" (hybrid search)
+
+   **1. [Score: 0.95] [Vector+FTS]**
+   Store: claude-code
+   File: 📄 path/to/file.ts
+   Purpose: → Purpose description here
+   Top Terms: 🔑 (in this chunk): concept1, concept2, concept3
+   Imports: 📦 (in this chunk): package1, package2
+
+   **2. [Score: 0.87] [Vector]**
+   Store: another-store
+   File: 📄 path/to/file.js
+   Purpose: → Another purpose here
+   Top Terms: 🔑 (in this chunk): other-concept
+
+   ---
+   **Found 10 results in 45ms**
+
+   💡 **Next Steps:**
+   - Read file: `Read /path/to/file.ts`
+   - Get full code: `mcp__bluera-knowledge__get_full_context("result-id")`
+   - Refine search: Use keywords above
+   ```
+
+   **Formatting rules:**
+   - Header: `## Search Results: "query" (mode search)` - Extract mode from response (vector/fts/hybrid)
+   - Each result on its own block with blank line between
+   - Result header: `**N. [Score: X.XX] {{method}}**` where method is:
+     - `[Vector+FTS]` if result.rankingMetadata has both vectorRank AND ftsRank (found by both methods)
+     - `[Vector]` if result.rankingMetadata has only vectorRank (semantic match only)
+     - `[Keyword]` if result.rankingMetadata has only ftsRank (keyword match only)
+   - Store: `Store: storeName` (on new line after header)
+   - File: `File: 📄 filename` (strip repoRoot prefix from location)
+   - Purpose: `Purpose: → purpose text` (keep concise)
+   - Top Terms: `Top Terms: 🔑 (in this chunk): ...` (top 5 most frequent words from this chunk, comma-separated)
+   - Imports: `Imports: 📦 (in this chunk): ...` (import statements from this chunk, first 3-4, comma-separated)
+   - Skip Top Terms/Imports lines if arrays are empty
+   - Footer: `**Found {{totalResults}} results in {{timeMs}}ms**` with separator line above
+
+4. For the footer next steps, include:
+   - First result's ID in the get_full_context example
+   - First result's actual file path in the Read example
+   - Use the actual keywords from top results
+
+5. If no results:
+   ```
+   No results found for "query"
+
+   Try:
+   - Broadening your search terms
+   - Checking indexed stores: /bluera-knowledge:stores
+   ```

package/commands/search.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# Search command that uses Python formatter for deterministic table output
+
+set -euo pipefail
+
+# Parse arguments
+QUERY=""
+STORES=""
+LIMIT=10
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --stores)
+      STORES="$2"
+      shift 2
+      ;;
+    --limit)
+      LIMIT="$2"
+      shift 2
+      ;;
+    *)
+      # Everything else is the query
+      if [ -z "$QUERY" ]; then
+        QUERY="$1"
+      else
+        QUERY="$QUERY $1"
+      fi
+      shift
+      ;;
+  esac
+done
+
+# Remove quotes from query if present
+QUERY=$(echo "$QUERY" | sed 's/^["'\'']*//;s/["'\'']*$//')
+
+if [ -z "$QUERY" ]; then
+  echo "Error: No search query provided"
+  exit 1
+fi
+
+# Build MCP tool call JSON
+TOOL_INPUT=$(cat <<EOF
+{
+  "query": "$QUERY",
+  "limit": $LIMIT,
+  "detail": "contextual",
+  "intent": "find-implementation"
+}
+EOF
+)
+
+# Call MCP tool (this would need to be done via Claude)
+# For now, output instructions for Claude
+cat <<EOF
+Please call mcp__bluera-knowledge__search with these parameters and pipe the results through the formatter:
+
+Query: $QUERY
+Limit: $LIMIT
+Detail: contextual
+Intent: find-implementation
+
+Then execute: echo '<results_json>' | ${CLAUDE_PLUGIN_ROOT}/hooks/format-search-results.py
+EOF

package/commands/stores.md

@@ -0,0 +1,54 @@
+---
+description: List all indexed library stores
+allowed-tools: ["mcp__bluera-knowledge__execute"]
+---
+
+# List Knowledge Stores
+
+Show all configured knowledge stores in the project.
+
+## Steps
+
+1. Use the mcp__bluera-knowledge__execute tool with command "stores" to retrieve all stores
+
+2. Present results in a clean table format:
+
+```
+| Name | Type | ID | Source |
+|------|------|----|--------------------|
+| react | repo | a1b2c3d4 | https://github.com/facebook/react |
+| lodash | repo | e5f6g7h8 | https://github.com/lodash/lodash |
+| my-docs | file | i9j0k1l2 | ~/docs |
+
+**Total**: 3 stores
+```
+
+3. Format each row:
+   - **Name**: The store name
+   - **Type**: Store type (repo, file, or web)
+   - **ID**: First 8 characters of the store ID (no ellipsis)
+   - **Source**:
+     - For repo stores: The git URL
+     - For file stores: The local path (use ~ for home directory to keep it concise)
+     - For web stores: The base URL
+
+## If No Stores Found
+
+If no stores exist, show:
+
+```
+## No Knowledge Stores Found
+
+You haven't created any knowledge stores yet.
+
+To get started:
+- `/bluera-knowledge:add-repo <url> --name=<name>` - Clone and index a library repository
+- `/bluera-knowledge:add-folder <path> --name=<name>` - Index a local folder of documentation
+
+Example:
+```
+/bluera-knowledge:add-repo https://github.com/facebook/react --name=react
+```
+
+After creating stores, they will be searchable via the MCP search tool.
+```

package/commands/suggest.md

@@ -0,0 +1,82 @@
+---
+description: Suggest important dependencies to add to knowledge stores
+allowed-tools: ["Glob", "Read", "mcp__bluera-knowledge__execute", "WebSearch"]
+---
+
+# Suggest Dependencies to Index
+
+Analyze project dependencies and suggest important libraries to add to knowledge stores.
+
+## Steps
+
+1. **Find dependency files** using Glob tool:
+   - `**/package.json` (JavaScript/TypeScript projects)
+   - `**/requirements.txt` (Python projects)
+   - `**/go.mod` (Go projects)
+   - `**/Cargo.toml` (Rust projects)
+
+2. **Read and parse dependencies**:
+   - Use Read tool to read each dependency file
+   - Extract package names and usage patterns
+   - For package.json: dependencies and devDependencies
+   - For requirements.txt: all packages
+   - For go.mod: require statements
+   - For Cargo.toml: dependencies section
+
+3. **Scan for import statements** using Glob + Read:
+   - Find all source files (*.js, *.ts, *.py, *.go, *.rs)
+   - Count imports/requires for each dependency
+   - Rank dependencies by frequency of use
+
+4. **Get existing stores** using mcp__bluera-knowledge__execute with command "stores":
+   - Filter out dependencies already in stores
+   - Focus on new suggestions
+
+5. **Find repository URLs** using WebSearch:
+   - For top 5 most-used dependencies
+   - Search for official GitHub/GitLab repositories
+   - Prefer official repos over forks
+
+6. **Display suggestions**:
+
+```
+## Dependency Analysis
+
+Scanned 342 source files and found 24 dependencies.
+
+### Top Dependencies by Usage
+
+1. **react** (147 imports across 52 files)
+   Repository: https://github.com/facebook/react
+
+   Add with:
+   ```
+   /bluera-knowledge:add-repo https://github.com/facebook/react --name=react
+   ```
+
+2. **lodash** (89 imports across 31 files)
+   Repository: https://github.com/lodash/lodash
+
+   Add with:
+   ```
+   /bluera-knowledge:add-repo https://github.com/lodash/lodash --name=lodash
+   ```
+
+[Continue for top 5...]
+
+---
+
+Already indexed: typescript, express, jest
+```
+
+## If No Dependencies Found
+
+```
+No external dependencies found in this project.
+
+Make sure you have a dependency manifest file:
+- package.json (JavaScript/TypeScript)
+- requirements.txt or pyproject.toml (Python)
+- go.mod (Go)
+- Cargo.toml (Rust)
+```