bluera-knowledge 0.13.0 → 0.13.2

package/docs/commands.md

@@ -0,0 +1,392 @@
+# Commands Reference
+
+Complete reference for all Bluera Knowledge slash commands.
+
+## Quick Reference
+
+| Command | Purpose | Arguments |
+|---------|---------|-----------|
+| `/bluera-knowledge:suggest` | Analyze project dependencies | None |
+| `/bluera-knowledge:add-repo` | Clone and index Git repository | `<url> [--name=<name>] [--branch=<branch>]` |
+| `/bluera-knowledge:add-folder` | Index local folder | `<path> --name=<name>` |
+| `/bluera-knowledge:search` | Search knowledge stores | `"<query>" [--stores=<names>] [--limit=<N>]` |
+| `/bluera-knowledge:stores` | List all stores | None |
+| `/bluera-knowledge:index` | Re-index a store | `<store-name-or-id>` |
+| `/bluera-knowledge:remove-store` | Delete a store and all data | `<store-name-or-id>` |
+| `/bluera-knowledge:crawl` | Crawl web pages | `<url> <store-name> [--crawl "<instruction>"]` |
+| `/bluera-knowledge:sync` | Sync stores from definitions config | `[--dry-run] [--prune]` |
+
+---
+
+## `/bluera-knowledge:suggest`
+
+**Analyze your project to suggest libraries worth indexing as knowledge stores**
+
+```bash
+/bluera-knowledge:suggest
+```
+
+Scans source files, counts import statements, and suggests the top 5 most-used dependencies with their repository URLs.
+
+**Supported languages:**
+
+| Language | Manifest File | Registry |
+|----------|---------------|----------|
+| JavaScript/TypeScript | `package.json` | NPM |
+| Python | `requirements.txt`, `pyproject.toml` | PyPI |
+| Rust | `Cargo.toml` | crates.io |
+| Go | `go.mod` | Go modules |
+
+<details>
+<summary><b>Expected Output</b></summary>
+
+```
+## Dependency Analysis
+
+Scanned 342 source files and found 24 dependencies.
+
+### Top Dependencies by Usage
+
+1. **react** (156 imports across 87 files)
+   Repository: https://github.com/facebook/react
+
+   Add with:
+   /bluera-knowledge:add-repo https://github.com/facebook/react --name=react
+
+2. **vitest** (40 imports across 40 files)
+   Repository: https://github.com/vitest-dev/vitest
+
+   Add with:
+   /bluera-knowledge:add-repo https://github.com/vitest-dev/vitest --name=vitest
+
+3. **lodash** (28 imports across 15 files)
+   Repository: https://github.com/lodash/lodash
+
+   Add with:
+   /bluera-knowledge:add-repo https://github.com/lodash/lodash --name=lodash
+
+---
+
+Already indexed: typescript, express
+```
+</details>
+
+---
+
+## `/bluera-knowledge:add-repo`
+
+**Clone and index a Git repository**
+
+```bash
+/bluera-knowledge:add-repo <url> [--name=<name>] [--branch=<branch>]
+```
+
+**Examples:**
+```bash
+/bluera-knowledge:add-repo https://github.com/lodash/lodash
+/bluera-knowledge:add-repo https://github.com/facebook/react --branch=main --name=react
+```
+
+<details>
+<summary><b>Expected Output</b></summary>
+
+```
+✓ Cloning https://github.com/facebook/react...
+✓ Created store: react (a1b2c3d4...)
+  Location: ~/.local/share/bluera-knowledge/stores/a1b2c3d4.../
+
+✓ Indexing...
+✓ Indexed 1,247 files
+
+Store is ready for searching!
+```
+</details>
+
+---
+
+## `/bluera-knowledge:add-folder`
+
+**Index a local folder**
+
+```bash
+/bluera-knowledge:add-folder <path> --name=<name>
+```
+
+**Use cases:**
+- Project documentation
+- Coding standards
+- Design documents
+- API specifications
+- Reference materials
+- Any other content
+
+**Examples:**
+```bash
+/bluera-knowledge:add-folder ./docs --name=project-docs
+/bluera-knowledge:add-folder ./architecture --name=design-docs
+```
+
+<details>
+<summary><b>Expected Output</b></summary>
+
+```
+✓ Adding folder: ~/my-project/docs...
+✓ Created store: project-docs (e5f6g7h8...)
+  Location: ~/.local/share/bluera-knowledge/stores/e5f6g7h8.../
+
+✓ Indexing...
+✓ Indexed 342 files
+
+Store is ready for searching!
+```
+</details>
+
+---
+
+## `/bluera-knowledge:search`
+
+**Search across indexed knowledge stores**
+
+```bash
+/bluera-knowledge:search "<query>" [--stores=<names>] [--limit=<number>] [--min-relevance=<0-1>]
+```
+
+**Options:**
+- `--stores=<names>` - Comma-separated store names to search (default: all stores)
+- `--limit=<number>` - Maximum results to return (default: 10)
+- `--min-relevance=<0-1>` - Minimum raw cosine similarity; returns empty if no results meet threshold
+- `--threshold=<0-1>` - Minimum normalized score to include results
+- `--mode=<mode>` - Search mode: `hybrid` (default), `vector`, or `fts`
+- `--detail=<level>` - Context detail: `minimal` (default), `contextual`, or `full`
+
+**Examples:**
+```bash
+# Search all stores
+/bluera-knowledge:search "how to invalidate queries"
+
+# Search specific store
+/bluera-knowledge:search "useState implementation" --stores=react
+
+# Search multiple stores (comma-separated)
+/bluera-knowledge:search "deep clone" --stores=react,lodash
+
+# Limit results
+/bluera-knowledge:search "testing patterns" --limit=5
+
+# Filter irrelevant results (returns empty if nothing is truly relevant)
+/bluera-knowledge:search "kubernetes deployment" --min-relevance=0.4
+```
+
+<details>
+<summary><b>Expected Output</b></summary>
+
+```
+## Search Results: "button component" (hybrid search)
+
+**1. [Score: 0.95] [Vector+FTS]**
+Store: react
+File: src/components/Button.tsx
+Purpose: → Reusable button component with variants
+Top Terms: (in this chunk): button, variant, size, color, onClick
+Imports: (in this chunk): React, clsx
+
+**2. [Score: 0.87] [Vector]**
+Store: react
+File: src/hooks/useButton.ts
+Purpose: → Custom hook for button state management
+Top Terms: (in this chunk): hook, state, pressed, disabled
+Imports: (in this chunk): useState, useCallback
+
+**3. [Score: 0.81] [Vector+FTS]**
+Store: react
+File: src/components/IconButton.tsx
+Purpose: → Button component with icon support
+Top Terms: (in this chunk): icon, button, aria-label, accessible
+
+---
+**Found 3 results in 45ms**
+
+**Next Steps:**
+- Read file: `Read src/components/Button.tsx`
+- Get full code: `mcp__bluera-knowledge__get_full_context("result-id")`
+- Refine search: Use keywords above
+```
+</details>
+
+---
+
+## `/bluera-knowledge:stores`
+
+**List all indexed knowledge stores**
+
+```bash
+/bluera-knowledge:stores
+```
+
+Shows store name, type, ID, and source location in a clean table format.
+
+<details>
+<summary><b>Expected Output</b></summary>
+
+```
+| Name | Type | ID | Source |
+|------|------|----|--------------------|
+| react | repo | 459747c7 | https://github.com/facebook/react |
+| crawl4ai | repo | b5a72a94 | https://github.com/unclecode/crawl4ai.git |
+| project-docs | file | 70f6309b | ~/repos/my-project/docs |
+| claude-docs | web | 9cc62018 | https://code.claude.com/docs |
+
+**Total**: 4 stores
+```
+</details>
+
+---
+
+## `/bluera-knowledge:index`
+
+**Re-index an existing store to update the search index**
+
+```bash
+/bluera-knowledge:index <store-name-or-id>
+```
+
+**When to re-index:**
+- The source repository has been updated (for repo stores)
+- Files have been added or modified (for file stores)
+- Search results seem out of date
+
+**Example:**
+```bash
+/bluera-knowledge:index react
+```
+
+<details>
+<summary><b>Expected Output</b></summary>
+
+```
+✓ Indexing store: react...
+✓ Indexed 1,247 documents in 3,421ms
+
+Store search index is up to date!
+```
+</details>
+
+---
+
+## `/bluera-knowledge:remove-store`
+
+**Delete a knowledge store and all associated data**
+
+```bash
+/bluera-knowledge:remove-store <store-name-or-id>
+```
+
+**What gets deleted:**
+- Store registry entry
+- LanceDB search index (vector embeddings)
+- Cloned repository files (for repo stores created from URLs)
+
+**Example:**
+```bash
+/bluera-knowledge:remove-store react
+```
+
+<details>
+<summary><b>Expected Output</b></summary>
+
+```
+Store "react" deleted successfully.
+
+Removed:
+- Store registry entry
+- LanceDB search index
+- Cloned repository files
+```
+</details>
+
+---
+
+## `/bluera-knowledge:crawl`
+
+**Crawl web pages with natural language control**
+
+```bash
+/bluera-knowledge:crawl <url> <store-name> [options]
+```
+
+**Options:**
+- `--crawl "<instruction>"` - Natural language instruction for which pages to crawl
+- `--extract "<instruction>"` - Natural language instruction for what content to extract
+- `--simple` - Use simple BFS mode instead of intelligent crawling
+- `--max-pages <n>` - Maximum pages to crawl (default: 50)
+- `--fast` - Use fast axios-only mode (may fail on JavaScript-heavy sites)
+
+**Requirements:**
+- Python 3 with `crawl4ai` package installed
+- Web store is auto-created if it doesn't exist
+
+**Examples:**
+```bash
+# Basic crawl
+/bluera-knowledge:crawl https://docs.example.com/guide my-docs
+
+# Intelligent crawl with custom strategy
+/bluera-knowledge:crawl https://react.dev react-docs --crawl "all API reference pages"
+
+# Extract specific content from pages
+/bluera-knowledge:crawl https://example.com/pricing pricing --extract "pricing tiers and features"
+
+# Combine crawl strategy + extraction
+/bluera-knowledge:crawl https://docs.python.org python-docs \
+  --crawl "standard library modules" \
+  --extract "function signatures and examples"
+
+# JavaScript-rendered sites work by default (uses headless browser)
+/bluera-knowledge:crawl https://nextjs.org/docs nextjs-docs --max-pages 30
+
+# Fast mode for static HTML sites (axios-only, faster but may miss JS content)
+/bluera-knowledge:crawl https://example.com/static static-docs --fast --max-pages 100
+
+# Simple BFS mode (no AI guidance)
+/bluera-knowledge:crawl https://example.com/docs docs --simple --max-pages 100
+```
+
+The crawler converts pages to markdown and indexes them for semantic search.
+
+---
+
+## `/bluera-knowledge:sync`
+
+**Sync stores from definitions config (bootstrap on fresh clone)**
+
+```bash
+/bluera-knowledge:sync [options]
+```
+
+**Options:**
+- `--dry-run` - Show what would happen without making changes
+- `--prune` - Remove stores not in definitions
+- `--reindex` - Re-index existing stores after sync
+
+**Use cases:**
+- **Fresh clone**: Recreate all stores defined by the team
+- **Check status**: See which stores exist vs. defined
+- **Clean up**: Remove orphan stores not in config
+
+**Examples:**
+```bash
+# Preview what would be synced
+/bluera-knowledge:sync --dry-run
+
+# Sync all stores from definitions
+/bluera-knowledge:sync
+
+# Sync and remove orphan stores
+/bluera-knowledge:sync --prune
+```
+
+**How it works:**
+1. Reads store definitions from `.bluera/bluera-knowledge/stores.config.json`
+2. Creates any stores that don't exist locally
+3. Reports orphan stores (local stores not in definitions)
+4. Optionally prunes orphans with `--prune`

package/docs/crawler-architecture.md

@@ -0,0 +1,89 @@
+# Crawler Architecture
+
+The crawler defaults to **headless mode** (Playwright) for maximum compatibility with modern JavaScript-rendered sites. Use `--fast` for static HTML sites when speed is critical.
+
+## Default Mode (Headless - JavaScript-Rendered Sites)
+
+By default, the crawler uses Playwright via crawl4ai to render JavaScript content:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CLI
+    participant IntelligentCrawler
+    participant Axios
+    participant Claude
+
+    User->>CLI: crawl URL --crawl "instruction"
+    CLI->>IntelligentCrawler: crawl(url, {useHeadless: true})
+    IntelligentCrawler->>PythonBridge: fetchHeadless(url)
+    PythonBridge->>crawl4ai: AsyncWebCrawler.arun(url)
+    crawl4ai->>Playwright: Launch browser & render JS
+    Playwright-->>crawl4ai: Rendered HTML
+    crawl4ai-->>PythonBridge: {html, markdown, links}
+    PythonBridge-->>IntelligentCrawler: Rendered HTML
+    IntelligentCrawler->>Claude: determineCrawlUrls(html, instruction)
+    Note over Claude: Natural language instruction<br/>STILL FULLY ACTIVE
+    Claude-->>IntelligentCrawler: [urls to crawl]
+    loop For each URL
+        IntelligentCrawler->>PythonBridge: fetchHeadless(url)
+        PythonBridge->>crawl4ai: Render JS
+        crawl4ai-->>PythonBridge: HTML
+        PythonBridge-->>IntelligentCrawler: HTML
+        IntelligentCrawler->>IntelligentCrawler: Convert to markdown & index
+    end
+```
+
+## Fast Mode (Static Sites - `--fast`)
+
+For static HTML sites, use `--fast` for faster crawling with axios:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant CLI
+    participant IntelligentCrawler
+    participant Axios
+    participant Claude
+
+    User->>CLI: crawl URL --crawl "instruction" --fast
+    CLI->>IntelligentCrawler: crawl(url, {useHeadless: false})
+    IntelligentCrawler->>Axios: fetchHtml(url)
+    Axios-->>IntelligentCrawler: Static HTML
+    IntelligentCrawler->>Claude: determineCrawlUrls(html, instruction)
+    Claude-->>IntelligentCrawler: [urls to crawl]
+    loop For each URL
+        IntelligentCrawler->>Axios: fetchHtml(url)
+        Axios-->>IntelligentCrawler: HTML
+        IntelligentCrawler->>IntelligentCrawler: Convert to markdown & index
+    end
+```
+
+---
+
+## Key Points
+
+| Feature | Description |
+|---------|-------------|
+| **Default to headless** | Maximum compatibility with modern JavaScript-rendered sites (React, Vue, Next.js) |
+| **Fast mode available** | Use `--fast` for static HTML sites when speed is critical |
+| **Intelligent crawling preserved** | Claude Code CLI analyzes pages and selects URLs in both modes |
+| **Automatic fallback** | If headless fetch fails, automatically falls back to axios |
+
+---
+
+## Intelligent Mode vs Simple Mode
+
+The crawler operates in two modes depending on Claude Code CLI availability:
+
+| Mode | Requires Claude CLI | Behavior |
+|------|---------------------|----------|
+| **Intelligent** | Yes | Claude analyzes pages and selects URLs based on natural language instructions |
+| **Simple (BFS)** | No | Breadth-first crawl up to max depth (2 levels) |
+
+**Automatic detection:**
+- When Claude Code CLI is available: Full intelligent mode with `--crawl` and `--extract` instructions
+- When Claude Code CLI is unavailable: Automatically uses simple BFS mode
+- Clear messaging: "Claude CLI not found, using simple crawl mode"
+
+> **Note:** Install Claude Code to unlock `--crawl` (AI-guided URL selection) and `--extract` (AI content extraction). Without it, web crawling still works but uses simple BFS mode.

package/docs/mcp-integration.md

@@ -0,0 +1,130 @@
+# MCP Integration
+
+The plugin includes a Model Context Protocol server that exposes search tools for AI agents.
+
+> **Important:** Commands vs MCP Tools: You interact with the plugin using `/bluera-knowledge:` slash commands. Behind the scenes, these commands instruct Claude Code to use MCP tools (`mcp__bluera-knowledge__*`) which handle the actual operations. Commands provide the user interface, while MCP tools are the backend that AI agents use to access your knowledge stores.
+
+## Configuration
+
+The MCP server is configured in `.mcp.json` at the plugin root:
+
+```json
+{
+  "bluera-knowledge": {
+    "command": "node",
+    "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp/server.js"],
+    "env": {
+      "PROJECT_ROOT": "${PWD}",
+      "DATA_DIR": ".bluera/bluera-knowledge/data",
+      "CONFIG_PATH": ".bluera/bluera-knowledge/config.json"
+    }
+  }
+}
+```
+
+> **Note:** We use a separate `.mcp.json` file rather than inline `mcpServers` in `plugin.json` due to [Claude Code Bug #16143](https://github.com/anthropics/claude-code/issues/16143). This is the recommended pattern for Claude Code plugins.
+
+---
+
+## Context Efficiency Strategy
+
+### Why Only 3 MCP Tools?
+
+Every MCP tool exposed requires its full schema to be sent to Claude with each tool invocation. More tools = more tokens consumed before Claude can even respond.
+
+**Design decision:** Consolidate from 10+ tools down to 3:
+
+| Approach | Tool Count | Context Cost | Trade-off |
+|----------|------------|--------------|-----------|
+| Individual tools | 10+ | ~800+ tokens | Simple calls, high overhead |
+| **Consolidated (current)** | 3 | ~300 tokens | Minimal overhead, slightly longer commands |
+
+### How It Works
+
+1. **Native tools for common workflow** - `search` and `get_full_context` are the operations Claude uses most often, so they get dedicated tools with full schemas
+
+2. **Meta-tool for management** - The `execute` tool consolidates 8 store/job management commands into a single tool. Commands are discovered on-demand via `execute("commands")` or `execute("help", {command: "store:create"})`
+
+3. **Lazy documentation** - Command help isn't pre-sent with tool listings; it's discoverable when needed
+
+**Result:** ~60% reduction in context overhead for MCP tool listings, without sacrificing functionality.
+
+> **Tip:** This pattern—consolidating infrequent operations into a meta-tool while keeping high-frequency operations native—is a general strategy for MCP context efficiency.
+
+---
+
+## Available MCP Tools
+
+### `search`
+
+Semantic vector search across all indexed stores or a specific subset. Returns structured code units with relevance ranking.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | string | Search query (natural language, patterns, or type signatures) |
+| `intent` | string | Search intent: find-pattern, find-implementation, find-usage, find-definition, find-documentation |
+| `mode` | string | Search mode: hybrid (default), vector, or fts |
+| `detail` | string | Context level: minimal, contextual, or full |
+| `limit` | number | Maximum results (default: 10) |
+| `stores` | array | Array of specific store IDs to search (optional, searches all stores if not specified) |
+| `threshold` | number | Minimum normalized score (0-1) for filtering results |
+| `minRelevance` | number | Minimum raw cosine similarity (0-1) for filtering results |
+
+### `get_full_context`
+
+Retrieve complete code and context for a specific search result by ID.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `resultId` | string | The result ID from a previous search |
+
+### `execute`
+
+Meta-tool for store and job management. Consolidates 8 operations into one tool with subcommands.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `command` | string | Command to execute (see below) |
+| `args` | object | Command-specific arguments (optional) |
+
+**Available commands:**
+
+| Command | Args | Description |
+|---------|------|-------------|
+| `stores` | `type?` | List all knowledge stores |
+| `store:info` | `store` | Get detailed store information including file path |
+| `store:create` | `name`, `type`, `source`, `branch?`, `description?` | Create a new store |
+| `store:index` | `store` | Re-index an existing store |
+| `store:delete` | `store` | Delete a store and all data |
+| `stores:sync` | `dryRun?`, `prune?`, `reindex?` | Sync stores from definitions config |
+| `jobs` | `activeOnly?`, `status?` | List background jobs |
+| `job:status` | `jobId` | Check specific job status |
+| `job:cancel` | `jobId` | Cancel a running job |
+| `help` | `command?` | Show help for commands |
+| `commands` | - | List all available commands |
+
+---
+
+## Known Issues
+
+### MCP Configuration Pattern
+
+This plugin uses a separate `.mcp.json` file for MCP server configuration (rather than inline in `plugin.json`). This is the recommended pattern for Claude Code plugins due to [Bug #16143](https://github.com/anthropics/claude-code/issues/16143) where inline `mcpServers` may be ignored during plugin manifest parsing.
+
+If you're developing a Claude Code plugin with MCP integration, we recommend:
+1. Create a `.mcp.json` file at your plugin root
+2. Do NOT use inline `mcpServers` in `plugin.json`
+
+### Related Claude Code Bugs
+
+| Issue | Status | Description |
+|-------|--------|-------------|
+| [#16143](https://github.com/anthropics/claude-code/issues/16143) | Open | Inline `mcpServers` in plugin.json ignored |
+| [#13543](https://github.com/anthropics/claude-code/issues/13543) | Fixed v2.0.65 | .mcp.json files not copied to plugin cache |
+| [#18336](https://github.com/anthropics/claude-code/issues/18336) | Open | MCP plugin shows enabled but no resources available |

package/docs/token-efficiency.md

@@ -0,0 +1,91 @@
+# 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.
+
+## How It Works
+
+**Without Bluera Knowledge:**
+- Web searches return 5-10 results (~500-2,000 tokens each)
+- Total per search: **3,000-10,000 tokens**
+- Often need multiple searches to find the right answer
+- Lower signal-to-noise ratio (blog posts mixed with actual docs)
+
+**With Bluera Knowledge:**
+- Semantic search returns top 10 relevant code chunks (~200-400 tokens each)
+- Structured metadata (file paths, imports, purpose)
+- Total per search: **1,500-3,000 tokens**
+- Higher relevance due to vector search (fewer follow-up queries needed)
+
+---
+
+## Real-World Examples
+
+### Example 1: Library Implementation Question
+
+**Question:** "How does Express handle middleware errors?"
+
+| Approach | Token Cost | Result |
+|----------|-----------|--------|
+| **Web Search** | ~8,000 tokens (3 searches: general query → refined query → source code) | Blog posts + Stack Overflow + eventual guess |
+| **Bluera Knowledge** | ~2,000 tokens (1 semantic search) | Actual Express source code, authoritative |
+| **Savings** | **75% fewer tokens** | Higher accuracy |
+
+### Example 2: Dependency Exploration
+
+**Question:** "How does LanceDB's vector search work?"
+
+| Approach | Token Cost | Result |
+|----------|-----------|--------|
+| **Web Search** | ~9,500 tokens (General docs → API docs → fetch specific page) | Documentation, might miss implementation details |
+| **Bluera Knowledge** | ~1,500 tokens (Search returns source + tests + examples) | Source code from Python + Rust implementation |
+| **Savings** | **84% fewer tokens** | Complete picture |
+
+### Example 3: Version-Specific Behavior
+
+**Question:** "What changed in React 18's useEffect cleanup?"
+
+| Approach | Token Cost | Result |
+|----------|-----------|--------|
+| **Training Data** | 0 tokens (but might be outdated) | Uncertain if accurate for React 18 |
+| **Web Search** | ~5,000 tokens (Search changelog → blog posts → docs) | Mix of React 17 and 18 info |
+| **Bluera Knowledge** | ~2,000 tokens (Search indexed React 18 source) | Exact React 18 implementation |
+| **Savings** | **60% fewer tokens** | Version-accurate |
+
+---
+
+## When BK Uses More Tokens
+
+Bluera Knowledge isn't always the most token-efficient choice:
+
+| Scenario | Best Approach | Why |
+|----------|---------------|-----|
+| **Simple concept questions** ("What is a JavaScript closure?") | Training data | Claude already knows this (0 tokens) |
+| **Current events** ("Latest Next.js 15 release notes") | Web search | BK only has what you've indexed |
+| **General advice** ("How to structure a React app?") | Training data | Opinion-based, not code-specific |
+
+---
+
+## Summary: Token Savings by Query Type
+
+| Query Type | Typical Token Savings | When to Use BK |
+|------------|----------------------|----------------|
+| **Library internals** | 60-75% | Always |
+| **Version-specific behavior** | 50-70% | Always |
+| **"How does X work internally?"** | 70-85% | Always |
+| **API usage examples** | 40-60% | Recommended |
+| **General concepts** | -100% (uses more) | Skip BK |
+| **Current events** | -100% (uses more) | Skip BK |
+
+---
+
+## Best Practice
+
+**Default to BK for library questions.** It's cheap, fast, and authoritative:
+
+| 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.