bluera-knowledge 0.11.20 → 0.12.1

package/.claude/council-cache/1a43ed5977b8f29afc79a9bf5c4082ee5ad8338c42ab991a4241a48f80c1e46d.json

@@ -0,0 +1,7 @@
+{
+  "provider": "openai",
+  "model": "codex-mini-latest",
+  "prompt": "What are the best trigger keywords and patterns for a skill auto-activation system in a Claude Code plugin? Context: We're building a UserPromptSubmit hook for the bluera-knowledge plugin that detects when users would benefit from learning about specific skills. The 5 skills are: (1) knowledge-search - how to query indexed library sources, (2) when-to-query - deciding between BK vs Grep/Read, (3) search-optimization - optimizing search parameters, (4) advanced-workflows - multi-tool orchestration, (5) store-lifecycle - managing knowledge stores. Key insight: if a user already uses BK terminology, they don't need the skill suggested. We want to catch users who SHOULD be using BK but don't know it exists.",
+  "response": "Below is a bite‑sized “pattern cookbook” you can drop into your `UserPromptSubmit` hook in the bluera‑knowledge Claude Code plugin. The idea is simple:\n\n1. **Look for “natural” signals** that a user is trying to do something Blue‑Knowledge (BK) was built for, but  \n2. **Exclude** anyone already using BK lingo (e.g. “knowledge‑search,” “index,” “store,” “workflow”) so you don’t remind the experienced.\n\n---\n\n## 1. Skill → Trigger‑patterns matrix\n\n| Skill                | What it is                                                                                   | Trigger patterns (if user text _contains_)                                                                                                     | Exclude if user text _contains_                        |\n|:---------------------|:---------------------------------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------|\n| **knowledge‑search** | How to query an indexed library of docs/sources.                                             | `\\b(find|lookup|search|get me|show me|where can i find)\\b.*\\b(docs|documentation|references?|articles?)\\b`                                       | `\\bknowledge[- ]search\\b|\\bindex(ed)?\\b|\\bstore\\b`       |\n| **when‑to‑query**    | Deciding whether to use BK vs. grep/`read()` etc.                                             | `\\b(grep|read\\(\\)|scan files|open files manually|search local files)\\b|\\b(is there a better way)\\b`                                             | `\\bwhen[- ]to[- ]query\\b|\\bblue[- ]knowledge\\b`          |\n| **search‑optimization** | Tuning filters, relevance, context windows, metadata to get better hits.                   | `\\b(narrow|filter|refine|limit|boost|prioritize|sort)\\b.*\\b(results|hits|matches)\\b`                                                           | `\\bsearch[- ]optimization\\b|\\brelevance\\b|\\bcontext window\\b` |\n| **advanced‑workflows** | Chaining multiple tools/APIs, branching, retrieval‑then‑generation, tool orchestration.      | `\\b(chain|pipeline|orchestrate|automate|workflow|multi[- ]step|multi[- ]tool)\\b`                                                               | `\\badvanced[- ]workflows\\b|\\btool orchestration\\b`       |\n| **store‑lifecycle**   | Setting up/updating/archiving knowledge stores, versioning, pruning old info.               | `\\b(create|update|delete|archive|prune|version)\\b.*\\b(store|index|database|repository)\\b`                                                       | `\\bstore[- ]lifecycle\\b|\\bknowledge[- ]store\\b`          |\n\n---\n\n### 1.1. Example Regex snippets\n\n```js\n// snippet for knowledge-search\nconst KNOWLEDGE_SEARCH_RE = /\\b(?:find|lookup|search|get me|show me|where can i find)\\b.*\\b(?:docs|documentation|references?|articles?)\\b/i;\n\n// snippet for when-to-query\nconst WHEN_TO_QUERY_RE = /\\b(?:grep|read\\(\\)|scan files|open files manually|search local files)\\b|\\b(?:is there a better way)\\b/i;\n\n// snippet for store-lifecycle\nconst STORE_LIFECYCLE_RE = /\\b(?:create|update|delete|archive|prune|version)\\b.*\\b(?:store|index|database|repository)\\b/i;\n```\n\n---\n\n## 2. Putting it together in your hook\n\nBelow is a simplified example of how you might wire these patterns into a Claude Code `UserPromptSubmit` hook. You’ll want to adjust the messaging and localization to taste.\n\n```js\n/**\n * bluera-knowledge UserPromptSubmit hook\n * Detect users who could benefit from Blue‑Knowledge skills.\n */\nexport async function onUserPromptSubmit(event, ctx) {\n  const text = event.prompt.text;\n\n  // quick bailout: if they already speak BK\n  const hasBKTerm = /\\bknowledge[- ]search\\b|\\bwhen[- ]to[- ]query\\b|\\bsearch[- ]optimization\\b|\\badvanced[- ]workflows\\b|\\bstore[- ]lifecycle\\b|\\bblue[- ]knowledge\\b/i.test(text);\n  if (hasBKTerm) return;\n\n  // mapping skill → [pattern, user‐facing hint]\n  const SKILLS = [\n    {\n      name: \"knowledge-search\",\n      re: /\\b(?:find|lookup|search|get me|show me|where can i find)\\b.*\\b(?:docs|documentation|references?|articles?)\\b/i,\n      hint: \"🔍 You can try using our **knowledge‑search** feature to query indexed docs—no manual grepping needed!\"\n    },\n    {\n      name: \"when-to-query\",\n      re: /\\b(?:grep|read\\(\\)|scan files|open files manually|search local files)\\b|\\b(?:is there a better way)\\b/i,\n      hint: \"💡 Noticed you're grepping or opening files one by one. Our **when‑to‑query** guide helps decide BK vs. direct file search.\"\n    },\n    {\n      name: \"search-optimization\",\n      re: /\\b(?:narrow|filter|refine|limit|boost|prioritize|sort)\\b.*\\b(?:results|hits|matches)\\b/i,\n      hint: \"⚙️ Want more relevant hits? See our **search‑optimization** tips for tuning relevance and filters.\"\n    },\n    {\n      name: \"advanced-workflows\",\n      re: /\\b(?:chain|pipeline|orchestrate|automate|workflow|multi[- ]step|multi[- ]tool)\\b/i,\n      hint: \"🔗 Looking to chain tools or build pipelines? Check out **advanced‑workflows** for multi‑tool orchestration.\"\n    },\n    {\n      name: \"store-lifecycle\",\n      re: /\\b(?:create|update|delete|archive|prune|version)\\b.*\\b(?:store|index|database|repository)\\b/i,\n      hint: \"🗄️ Managing indexes or archiving old data? Our **store‑lifecycle** guide covers store setup, pruning, and versioning.\"\n    }\n  ];\n\n  // find the first match\n  for (const skill of SKILLS) {\n    if (skill.re.test(text)) {\n      await ctx.reply({\n        type: \"skill-suggestion\",\n        skill: skill.name,\n        message: skill.hint\n      });\n      break;\n    }\n  }\n}\n```\n\n---\n\n## 3. Tuning tips\n\n1. **Balance precision/recall**:  \n   - Start _wide_: shorter patterns catch more but risk noise.  \n   - Refine as you gather real prompts: update regex to avoid false positives.\n\n2. **Avoid overlap**:  \n   If two patterns both match, pick the one that feels _most_ immediately helpful. (Above example picks the first.)\n\n3. **User‑facing copy**:  \n   Keep hints crisp, emoji‑tagged, and link directly to your docs or `@help` commands.\n\n4. **Metrics & feedback loop**:  \n   Log suggestions shown vs. accepted. Tune patterns around low‑acceptance hits.\n\n---\n\n### Summary\n\nBy combining simple regex‑based detectors with an exclusion of existing BK terminology, you’ll catch “hidden” use cases where users are laboring manually and would love a BK shortcut. Tweak patterns over time against your live traffic, and you’ll have a reliable auto‑activation layer that boosts discoverability _without_ nagging your power users.",
+  "timestamp": 1768432278
+}

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.11.20",
+  "version": "0.12.1",
   "description": "Clone repos, crawl docs, search locally. Fast, authoritative answers for AI coding agents.",
   "mcpServers": {
     "bluera-knowledge": {

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [0.12.1](https://github.com/blueraai/bluera-knowledge/compare/v0.11.21...v0.12.1) (2026-01-14)
+
+
+### Features
+
+* **hooks:** add PreToolUse hooks for BK suggestions ([23d3fa4](https://github.com/blueraai/bluera-knowledge/commit/23d3fa493dd16427d6bda3ea80064622c6244bba))
+* **hooks:** add skill auto-activation system ([2b4e96b](https://github.com/blueraai/bluera-knowledge/commit/2b4e96bd29f28df63377cdaacab922d4f4321a8f))
+
+## [0.12.0](https://github.com/blueraai/bluera-knowledge/compare/v0.11.21...v0.12.0) (2026-01-14)
+
+
+### Features
+
+* **hooks:** add skill auto-activation system ([2b4e96b](https://github.com/blueraai/bluera-knowledge/commit/2b4e96bd29f28df63377cdaacab922d4f4321a8f))
+
+## [0.11.21](https://github.com/blueraai/bluera-knowledge/compare/v0.11.20...v0.11.21) (2026-01-10)
+
+
+### Features
+
+* **cli:** add --branch option to store create command ([8b3209f](https://github.com/blueraai/bluera-knowledge/commit/8b3209f34e22f78df54fc6a64cf1d8b91833dabc))
+* **mcp:** add mode and threshold params to search tool ([18acdb5](https://github.com/blueraai/bluera-knowledge/commit/18acdb590944b9e1ebf1851d0eab32f746ac1758))
+* **sync:** add --reindex flag to sync command ([1344d98](https://github.com/blueraai/bluera-knowledge/commit/1344d984fdc5a75b25687d55ad186416d14203a9))
+
+
+### Bug Fixes
+
+* **code-graph:** preserve confidence in serialized edges ([d88c342](https://github.com/blueraai/bluera-knowledge/commit/d88c342e4225f984db02691437ab1c54d29ad07d))
+* **job-service:** throw on missing HOME/USERPROFILE env vars ([b0a79fb](https://github.com/blueraai/bluera-knowledge/commit/b0a79fbe996c5e4e333ce4ad7a338cdda4af2d70))
+* **store:** clean up all resources on store deletion ([fbcff02](https://github.com/blueraai/bluera-knowledge/commit/fbcff02f304e8b330c1656db32f6b237a63f3295))
+
 ## [0.11.20](https://github.com/blueraai/bluera-knowledge/compare/v0.11.6...v0.11.20) (2026-01-10)
 
 

package/README.md

@@ -1248,9 +1248,12 @@ The plugin exposes 3 MCP tools optimized for minimal context overhead:
 **Parameters:**
 - `query` - Search query (natural language, patterns, or type signatures)
 - `intent` - Search intent: find-pattern, find-implementation, find-usage, find-definition, find-documentation
+- `mode` - Search mode: hybrid (default), vector, or fts
 - `detail` - Context level: minimal, contextual, or full
 - `limit` - Maximum results (default: 10)
 - `stores` - Array of specific store IDs to search (optional, searches all stores if not specified)
+- `threshold` - Minimum normalized score (0-1) for filtering results
+- `minRelevance` - Minimum raw cosine similarity (0-1) for filtering results
 
 #### `get_full_context`
 📖 Retrieve complete code and context for a specific search result by ID.
@@ -1311,6 +1314,9 @@ npm install --save-dev bluera-knowledge
 # Add a Git repository
 bluera-knowledge store create react --type repo --source https://github.com/facebook/react
 
+# Add a Git repository with specific branch
+bluera-knowledge store create react-canary --type repo --source https://github.com/facebook/react --branch canary
+
 # Add a local folder
 bluera-knowledge store create my-docs --type file --source ./docs
 
@@ -1318,12 +1324,33 @@ bluera-knowledge store create my-docs --type file --source ./docs
 bluera-knowledge store create fastapi-docs --type web --source https://fastapi.tiangolo.com
 ```
 
+**Create Options:**
+- `-t, --type <type>` - Store type: `file`, `repo`, or `web` (required)
+- `-s, --source <path>` - Local path or URL (required)
+- `-b, --branch <branch>` - Git branch to clone (repo stores only)
+- `-d, --description <desc>` - Optional store description
+- `--tags <tags>` - Comma-separated tags for filtering
+
 #### Index a Store
 
 ```bash
+# Re-index a store (only changed files)
 bluera-knowledge index react
+
+# Force re-index all files (ignores cache)
+bluera-knowledge index react --force
+
+# Watch for changes and auto-reindex
+bluera-knowledge index watch react
+bluera-knowledge index watch react --debounce 2000  # Custom debounce (default: 1000ms)
 ```
 
+**Index Options:**
+- `-f, --force` - Re-index all files (ignore incremental cache)
+
+**Watch Options:**
+- `--debounce <ms>` - Debounce delay for file changes (default: 1000ms)
+
 #### Search
 
 ```bash
@@ -1368,17 +1395,27 @@ bluera-knowledge store info react
 #### Delete a Store
 
 ```bash
+# Interactive deletion (prompts for confirmation in TTY mode)
 bluera-knowledge store delete old-store
+
+# Force delete without confirmation
+bluera-knowledge store delete old-store --force
+bluera-knowledge store delete old-store -y
 ```
 
+**Delete Options:**
+- `-f, --force` - Delete without confirmation prompt
+- `-y, --yes` - Alias for `--force`
+
 ### Global Options
 
 ```bash
---config <path>      # Custom config file
---data-dir <path>    # Custom data directory
---format <format>    # Output format: json | table | plain
---quiet              # Suppress non-essential output
---verbose            # Enable verbose logging
+--config <path>        # Custom config file
+--data-dir <path>      # Custom data directory
+--project-root <path>  # Project root for store definitions (required for sync)
+--format <format>      # Output format: json | table | plain
+--quiet                # Suppress non-essential output
+--verbose              # Enable verbose logging
 ```
 
 ### When to Use CLI vs Plugin
@@ -1449,6 +1486,28 @@ This hybrid approach reduces unnecessary tool calls and context usage while main
 
 Result: Fewer tool calls, more accurate results, less context consumed.
 
+### 🎯 Skill Auto-Activation
+
+Skills can automatically suggest themselves when your prompt matches certain patterns.
+
+**Toggle via slash command:**
+- `/bluera-knowledge:skill-activation` - Show current status
+- `/bluera-knowledge:skill-activation on` - Enable (default)
+- `/bluera-knowledge:skill-activation off` - Disable
+- `/bluera-knowledge:skill-activation config` - Toggle individual skills
+
+**How it works:**
+When enabled, a UserPromptSubmit hook analyzes your prompt for patterns like:
+- "How does [library] work?" → suggests `knowledge-search`
+- "Should I grep or search?" → suggests `when-to-query`
+- "Too many results" → suggests `search-optimization`
+- "Multi-step workflow" → suggests `advanced-workflows`
+- "Add/delete store" → suggests `store-lifecycle`
+
+Claude evaluates each suggestion and invokes relevant skills before answering. Users who already use BK terminology are excluded (they already know the tool).
+
+**Configuration stored in:** `~/.local/share/bluera-knowledge/skill-activation.json`
+
 ---
 
 ## 💾 Data Storage

package/commands/crawl.md

@@ -1,6 +1,6 @@
 ---
 description: Crawl web pages with natural language control and add to knowledge store
-argument-hint: "[url] [store-name] [--crawl instruction] [--extract instruction]"
+argument-hint: "[url] [store-name] [--crawl instruction] [--extract instruction] [--fast]"
 allowed-tools: [Bash(*)]
 ---
 
@@ -36,9 +36,9 @@ The web pages will be crawled with intelligent link selection and optional natur
 /bluera-knowledge:crawl https://example.com/docs docs-store --simple
 ```
 
-**Headless browser for JavaScript-rendered sites:**
+**Fast mode (axios-only, no JavaScript rendering):**
 ```
-/bluera-knowledge:crawl https://code.claude.com/docs claude-docs --headless --max-pages 20
+/bluera-knowledge:crawl https://example.com/docs docs-store --fast --max-pages 20
 ```
 
 ## Options
@@ -47,7 +47,7 @@ The web pages will be crawled with intelligent link selection and optional natur
 - `--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
+- `--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/commands/search.md

@@ -1,6 +1,6 @@
 ---
 description: Search indexed library sources
-argument-hint: "[query] [--stores names] [--limit N]"
+argument-hint: "[query] [--stores names] [--limit N] [--mode vector|fts|hybrid] [--detail minimal|contextual|full] [--threshold 0-1] [--min-relevance 0-1]"
 allowed-tools: ["mcp__bluera-knowledge__search"]
 ---
 
@@ -14,12 +14,19 @@ Search indexed library sources for: **$ARGUMENTS**
    - Extract the search query (required)
    - Extract --stores parameter (optional, comma-separated store names)
    - Extract --limit parameter (optional, default 10)
+   - Extract --mode parameter (optional: vector, fts, hybrid; default hybrid)
+   - Extract --detail parameter (optional: minimal, contextual, full; default contextual)
+   - Extract --threshold parameter (optional, 0-1 range for normalized score filtering)
+   - Extract --min-relevance parameter (optional, 0-1 range for raw cosine similarity filtering)
 
 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"
+   - mode: Search mode (if --mode specified, default "hybrid")
+   - detail: Detail level (if --detail specified, default "contextual")
+   - threshold: Minimum normalized score (if --threshold specified)
+   - minRelevance: Minimum raw cosine similarity (if --min-relevance specified)
    - intent: "find-implementation"
 
 3. Format and display results with rich context:

package/commands/skill-activation.md

@@ -0,0 +1,130 @@
+---
+description: Toggle skill auto-activation on/off or configure individual skills
+argument-hint: "[on|off|status|config]"
+allowed-tools: ["Read", "Write", "AskUserQuestion"]
+---
+
+# Skill Activation Configuration
+
+Manage the bluera-knowledge skill auto-activation system.
+
+## Configuration File
+
+Location: `~/.local/share/bluera-knowledge/skill-activation.json`
+
+Default configuration (created if missing):
+```json
+{
+  "enabled": true,
+  "threshold": 1,
+  "skills": {
+    "knowledge-search": true,
+    "when-to-query": true,
+    "search-optimization": true,
+    "advanced-workflows": true,
+    "store-lifecycle": true
+  }
+}
+```
+
+## Steps
+
+### 1. Parse Arguments
+
+Extract the subcommand from $ARGUMENTS:
+- Empty or "status": Show current status
+- "on": Enable skill activation
+- "off": Disable skill activation
+- "config": Interactive skill configuration
+
+### 2. Read Current Configuration
+
+Read `~/.local/share/bluera-knowledge/skill-activation.json`
+
+If the file doesn't exist, use the default configuration shown above.
+
+### 3. Execute Subcommand
+
+**For "status" or empty arguments:**
+
+Display the current configuration:
+
+```
+## Skill Activation Status
+
+**Status**: [Enabled/Disabled]
+**Threshold**: [threshold value]
+
+### Individual Skills
+| Skill | Status |
+|-------|--------|
+| knowledge-search | enabled/disabled |
+| when-to-query | enabled/disabled |
+| search-optimization | enabled/disabled |
+| advanced-workflows | enabled/disabled |
+| store-lifecycle | enabled/disabled |
+
+Use `/bluera-knowledge:skill-activation config` to toggle individual skills.
+```
+
+**For "on":**
+
+1. Read configuration (or use defaults)
+2. Set `enabled: true`
+3. Ensure directory exists: `~/.local/share/bluera-knowledge/`
+4. Write updated configuration
+5. Confirm: "Skill activation **enabled**. Skills will be suggested based on your prompts."
+
+**For "off":**
+
+1. Read configuration (or use defaults)
+2. Set `enabled: false`
+3. Write updated configuration
+4. Confirm: "Skill activation **disabled**. No skill suggestions will appear."
+
+**For "config":**
+
+1. Read current configuration
+2. Use AskUserQuestion to let user toggle skills:
+
+```json
+{
+  "questions": [{
+    "question": "Which skills should auto-activate when relevant patterns are detected?",
+    "header": "Skills",
+    "multiSelect": true,
+    "options": [
+      {
+        "label": "knowledge-search",
+        "description": "Suggests when to query BK for library questions"
+      },
+      {
+        "label": "when-to-query",
+        "description": "Guides BK vs Grep/Read decisions"
+      },
+      {
+        "label": "search-optimization",
+        "description": "Tips for optimizing search parameters"
+      },
+      {
+        "label": "advanced-workflows",
+        "description": "Multi-tool orchestration patterns"
+      },
+      {
+        "label": "store-lifecycle",
+        "description": "Managing knowledge stores"
+      }
+    ]
+  }]
+}
+```
+
+3. Update skills based on selection (selected = enabled, unselected = disabled)
+4. Write updated configuration
+5. Show updated status table
+
+## Notes
+
+- The configuration directory is created automatically if it doesn't exist
+- Changes take effect immediately on the next prompt
+- When disabled globally, no skills are suggested regardless of individual settings

package/dist/{chunk-MQGRQ2EG.js → chunk-C4SYGLAI.js}

@@ -262,10 +262,16 @@ function err(error) {
 var JobService = class {
   jobsDir;
   constructor(dataDir) {
-    const baseDir = dataDir ?? path.join(
-      process.env["HOME"] ?? process.env["USERPROFILE"] ?? ".",
-      ".local/share/bluera-knowledge"
-    );
+    let baseDir;
+    if (dataDir !== void 0) {
+      baseDir = dataDir;
+    } else {
+      const homeDir = process.env["HOME"] ?? process.env["USERPROFILE"];
+      if (homeDir === void 0) {
+        throw new Error("HOME or USERPROFILE environment variable is required");
+      }
+      baseDir = path.join(homeDir, ".local/share/bluera-knowledge");
+    }
     this.jobsDir = path.join(baseDir, "jobs");
     if (!fs.existsSync(this.jobsDir)) {
       fs.mkdirSync(this.jobsDir, { recursive: true });
@@ -451,7 +457,7 @@ var JobService = class {
 };
 
 // src/services/code-graph.service.ts
-import { readFile, writeFile, mkdir } from "fs/promises";
+import { readFile, writeFile, mkdir, rm } from "fs/promises";
 import { join as join3, dirname } from "path";
 
 // src/analysis/ast-parser.ts
@@ -763,7 +769,12 @@ var CodeGraph = class {
     }
     return {
       nodes: Array.from(this.nodes.values()),
-      edges: allEdges.map((e) => ({ from: e.from, to: e.to, type: e.type }))
+      edges: allEdges.map((e) => ({
+        from: e.from,
+        to: e.to,
+        type: e.type,
+        confidence: e.confidence
+      }))
     };
   }
 };
@@ -1668,6 +1679,15 @@ var CodeGraphService = class {
     const serialized = graph.toJSON();
     await writeFile(graphPath, JSON.stringify(serialized, null, 2));
   }
+  /**
+   * Delete the code graph file for a store.
+   * Silently succeeds if the file doesn't exist.
+   */
+  async deleteGraph(storeId) {
+    const graphPath = this.getGraphPath(storeId);
+    await rm(graphPath, { force: true });
+    this.graphCache.delete(storeId);
+  }
   /**
    * Load a code graph for a store.
    * Returns undefined if no graph exists.
@@ -4518,4 +4538,4 @@ export {
   createServices,
   destroyServices
 };
-//# sourceMappingURL=chunk-MQGRQ2EG.js.map
+//# sourceMappingURL=chunk-C4SYGLAI.js.map