bluera-knowledge 0.11.21 → 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.21",
+  "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,21 @@
 
 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)
 
 

package/README.md

@@ -1486,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/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/hooks/hooks.json

@@ -1,6 +1,28 @@
 {
-  "description": "bluera-knowledge plugin hooks - automatic dependency checking and job status monitoring",
+  "description": "bluera-knowledge plugin hooks - dependency checking, job monitoring, and BK suggestions",
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse-bk-reminder.py",
+            "timeout": 3
+          }
+        ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/pretooluse-bk-reminder.py",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
     "SessionStart": [
       {
         "hooks": [
@@ -19,6 +41,11 @@
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/job-status-hook.sh",
             "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/skill-activation.py",
+            "timeout": 5
           }
         ]
       }

package/hooks/pretooluse-bk-reminder.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+PreToolUse hook for bluera-knowledge plugin.
+Fires when Claude is about to Grep/Read in dependency directories,
+reminding to consider using BK instead.
+"""
+
+import json
+import re
+import sys
+from typing import Any
+
+# Patterns indicating library/dependency code
+LIBRARY_PATH_PATTERNS = [
+    r"node_modules/",
+    r"vendor/",
+    r"site-packages/",
+    r"\.venv/",
+    r"venv/",
+    r"bower_components/",
+    r"packages/.*/node_modules/",
+    r"\.npm/",
+    r"\.cargo/registry/",
+    r"go/pkg/mod/",
+]
+
+# Compile patterns for efficiency
+LIBRARY_PATTERNS_RE = re.compile("|".join(LIBRARY_PATH_PATTERNS), re.IGNORECASE)
+
+
+def check_grep_tool(tool_input: dict[str, Any]) -> str | None:
+    """Check if Grep is targeting library code."""
+    path = tool_input.get("path", "")
+    pattern = tool_input.get("pattern", "")
+
+    # Check if searching in library directories
+    if path and LIBRARY_PATTERNS_RE.search(path):
+        return f"grep in `{path}`"
+
+    # Check if pattern suggests library-specific search
+    # (searching for common library internals)
+    return None
+
+
+def check_read_tool(tool_input: dict[str, Any]) -> str | None:
+    """Check if Read is targeting library code."""
+    file_path = tool_input.get("file_path", "")
+
+    if file_path and LIBRARY_PATTERNS_RE.search(file_path):
+        return f"read `{file_path}`"
+
+    return None
+
+
+def main() -> int:
+    try:
+        stdin_data = sys.stdin.read()
+        if not stdin_data.strip():
+            return 0
+        hook_input = json.loads(stdin_data)
+    except json.JSONDecodeError:
+        return 0
+
+    tool_name = hook_input.get("tool_name", "")
+    tool_input = hook_input.get("tool_input", {})
+
+    trigger_reason = None
+
+    if tool_name == "Grep":
+        trigger_reason = check_grep_tool(tool_input)
+    elif tool_name == "Read":
+        trigger_reason = check_read_tool(tool_input)
+
+    if not trigger_reason:
+        return 0
+
+    # Output reminder
+    reminder = f"""<system-reminder>
+BLUERA-KNOWLEDGE SUGGESTION
+
+You're about to {trigger_reason} which appears to be dependency/library code.
+
+Consider querying Bluera Knowledge instead:
+- Use MCP tool `search` with a relevant query
+- Or invoke `/bluera-knowledge:search <query>`
+
+BK provides indexed, searchable access to library sources - faster and more context-efficient than grepping through node_modules.
+
+If you don't have this library indexed, continue with your current approach.
+</system-reminder>"""
+
+    print(reminder)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/skill-activation.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""
+Skill activation hook for bluera-knowledge plugin.
+Matches user prompts against skill rules and injects activation reminders.
+
+Runs on UserPromptSubmit to detect users who would benefit from learning
+about BK skills, while excluding users who already know BK terminology.
+"""
+
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+CONFIG_DIR = Path.home() / ".local" / "share" / "bluera-knowledge"
+CONFIG_FILE = CONFIG_DIR / "skill-activation.json"
+DEFAULT_CONFIG: dict[str, Any] = {
+    "enabled": True,
+    "threshold": 1,
+    "skills": {
+        "knowledge-search": True,
+        "when-to-query": True,
+        "search-optimization": True,
+        "advanced-workflows": True,
+        "store-lifecycle": True,
+    },
+}
+
+
+def load_config() -> dict[str, Any]:
+    """Load skill activation configuration."""
+    if not CONFIG_FILE.exists():
+        return DEFAULT_CONFIG.copy()
+    try:
+        with open(CONFIG_FILE, encoding="utf-8") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return DEFAULT_CONFIG.copy()
+
+
+def load_rules(plugin_root: Path) -> dict[str, Any]:
+    """Load skill rules from plugin hooks directory."""
+    rules_path = plugin_root / "hooks" / "skill-rules.json"
+    if not rules_path.exists():
+        return {"skills": [], "threshold": 1, "globalExclusions": []}
+    with open(rules_path, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def matches_condition(prompt: str, condition: dict[str, Any]) -> bool:
+    """Check if prompt matches a single condition (keyword or regex)."""
+    prompt_lower = prompt.lower()
+    if "keyword" in condition:
+        return condition["keyword"].lower() in prompt_lower
+    if "regex" in condition:
+        return bool(re.search(condition["regex"], prompt, flags=re.IGNORECASE))
+    return False
+
+
+def check_exclusions(
+    prompt: str, exclusions: list[dict[str, Any]]
+) -> bool:
+    """Check if any exclusion pattern matches. Returns True if excluded."""
+    for exc in exclusions:
+        if matches_condition(prompt, exc):
+            return True
+    return False
+
+
+def score_skill(
+    prompt: str, skill: dict[str, Any]
+) -> tuple[int, list[str]]:
+    """Score a skill against the user prompt. Returns (score, reasons)."""
+    reasons: list[str] = []
+    score = 0
+
+    # Check skill-specific exclusions first
+    if check_exclusions(prompt, skill.get("exclusions", [])):
+        return 0, []
+
+    for trigger in skill.get("triggers", []):
+        if matches_condition(prompt, trigger):
+            weight = trigger.get("weight", 1)
+            score += weight
+            if "keyword" in trigger:
+                reasons.append(f'keyword "{trigger["keyword"]}"')
+            elif "regex" in trigger:
+                reasons.append(f'pattern match')
+
+    return score, reasons
+
+
+def generate_reminder(
+    matches: list[tuple[str, int, list[str], str]]
+) -> str:
+    """Generate the system-reminder for matched skills."""
+    lines = [
+        "<system-reminder>",
+        "BLUERA-KNOWLEDGE SKILL ACTIVATION",
+        "",
+        "The user's prompt suggests they may benefit from these skills.",
+        "For EACH skill below, decide YES/NO:",
+        "- YES: Invoke via Skill tool: Skill(skill='bluera-knowledge:<skill-name>')",
+        "- NO: Skip (user doesn't need this guidance)",
+        "",
+        "Candidate skills (ranked by relevance):",
+    ]
+
+    for name, score, reasons, description in matches:
+        lines.append(f"")
+        lines.append(f"  [{name}] (score={score})")
+        lines.append(f"  Purpose: {description}")
+        lines.append(f"  Matched: {', '.join(reasons[:3])}")
+
+    lines.append("")
+    lines.append("Evaluate quickly, then answer the user's question.")
+    lines.append("</system-reminder>")
+
+    return "\n".join(lines)
+
+
+def main() -> int:
+    # Load configuration
+    config = load_config()
+
+    # Check if skill activation is enabled
+    if not config.get("enabled", True):
+        return 0
+
+    # Get plugin root from environment
+    plugin_root_env = os.environ.get("CLAUDE_PLUGIN_ROOT", "")
+    if not plugin_root_env:
+        return 0
+    plugin_root = Path(plugin_root_env)
+
+    # Read hook input from stdin
+    try:
+        stdin_data = sys.stdin.read()
+        if not stdin_data.strip():
+            return 0
+        hook_input = json.loads(stdin_data)
+    except json.JSONDecodeError:
+        return 0
+
+    prompt = hook_input.get("prompt", "")
+    if not prompt.strip():
+        return 0
+
+    # Load rules
+    rules = load_rules(plugin_root)
+
+    # Check global exclusions first
+    if check_exclusions(prompt, rules.get("globalExclusions", [])):
+        return 0
+
+    threshold = config.get("threshold", rules.get("threshold", 1))
+    enabled_skills = config.get("skills", {})
+
+    # Score each skill
+    matches: list[tuple[str, int, list[str], str]] = []
+
+    for skill in rules.get("skills", []):
+        name = skill["name"]
+
+        # Skip disabled skills
+        if not enabled_skills.get(name, True):
+            continue
+
+        score, reasons = score_skill(prompt, skill)
+        if score >= threshold:
+            matches.append((name, score, reasons, skill.get("description", "")))
+
+    # No matches - silent exit
+    if not matches:
+        return 0
+
+    # Sort by score (highest first)
+    matches.sort(key=lambda t: t[1], reverse=True)
+
+    # Generate and output the reminder
+    reminder = generate_reminder(matches)
+    print(reminder)
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/hooks/skill-rules.json

@@ -0,0 +1,122 @@
+{
+  "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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bluera-knowledge",
-  "version": "0.11.21",
+  "version": "0.12.1",
   "description": "CLI tool for managing knowledge stores with semantic search",
   "type": "module",
   "bin": {

package/src/services/watch.service.test.ts

@@ -21,6 +21,9 @@ vi.mock('chokidar', () => ({
   }),
 }));
 
+// Import chokidar once after mock is set up to avoid dynamic import flakiness
+import * as chokidar from 'chokidar';
+
 describe('WatchService', () => {
   let watchService: WatchService;
   let mockIndexService: IndexService;
@@ -78,7 +81,7 @@ describe('WatchService', () => {
     const noopErrorHandler = (): void => {};
 
     it('starts watching a file store', async () => {
-      const { watch } = await import('chokidar');
+      const { watch } = chokidar;
 
       await watchService.watch(mockFileStore, 1000, undefined, noopErrorHandler);
 
@@ -93,7 +96,7 @@ describe('WatchService', () => {
     });
 
     it('starts watching a repo store', async () => {
-      const { watch } = await import('chokidar');
+      const { watch } = chokidar;
 
       await watchService.watch(mockRepoStore, 1000, undefined, noopErrorHandler);
 
@@ -109,7 +112,7 @@ describe('WatchService', () => {
     });
 
     it('does not start watching if already watching the same store', async () => {
-      const { watch } = await import('chokidar');
+      const { watch } = chokidar;
 
       await watchService.watch(mockFileStore, 1000, undefined, noopErrorHandler);
       const callCount1 = (watch as ReturnType<typeof vi.fn>).mock.calls.length;
@@ -121,7 +124,7 @@ describe('WatchService', () => {
     });
 
     it('allows watching multiple different stores', async () => {
-      const { watch } = await import('chokidar');
+      const { watch } = chokidar;
 
       await watchService.watch(mockFileStore, 1000, undefined, noopErrorHandler);
       await watchService.watch(mockRepoStore, 1000, undefined, noopErrorHandler);
@@ -454,7 +457,7 @@ describe('WatchService', () => {
     });
 
     it('removes watcher from internal map', async () => {
-      const { watch } = await import('chokidar');
+      const { watch } = chokidar;
 
       await watchService.watch(mockFileStore, 1000, undefined, noopErrorHandler);
       await watchService.unwatch(mockFileStore.id);
@@ -523,7 +526,7 @@ describe('WatchService', () => {
     });
 
     it('clears all watchers from map', async () => {
-      const { watch } = await import('chokidar');
+      const { watch } = chokidar;
 
       await watchService.watch(mockFileStore, 1000, undefined, noopErrorHandler);
       await watchService.watch(mockRepoStore, 1000, undefined, noopErrorHandler);
@@ -546,7 +549,7 @@ describe('WatchService', () => {
     const noopErrorHandler = (): void => {};
 
     it('ignores .git directories', async () => {
-      const { watch } = await import('chokidar');
+      const { watch } = chokidar;
 
       await watchService.watch(mockFileStore, 1000, undefined, noopErrorHandler);
 
@@ -557,7 +560,7 @@ describe('WatchService', () => {
     });
 
     it('ignores node_modules directories', async () => {
-      const { watch } = await import('chokidar');
+      const { watch } = chokidar;
 
       await watchService.watch(mockFileStore, 1000, undefined, noopErrorHandler);
 
@@ -567,7 +570,7 @@ describe('WatchService', () => {
     });
 
     it('ignores dist and build directories', async () => {
-      const { watch } = await import('chokidar');
+      const { watch } = chokidar;
 
       await watchService.watch(mockFileStore, 1000, undefined, noopErrorHandler);
 
@@ -577,7 +580,7 @@ describe('WatchService', () => {
     });
 
     it('sets persistent to true', async () => {
-      const { watch } = await import('chokidar');
+      const { watch } = chokidar;
 
       await watchService.watch(mockFileStore, 1000, undefined, noopErrorHandler);
 
@@ -586,7 +589,7 @@ describe('WatchService', () => {
     });
 
     it('sets ignoreInitial to true', async () => {
-      const { watch } = await import('chokidar');
+      const { watch } = chokidar;
 
       await watchService.watch(mockFileStore, 1000, undefined, noopErrorHandler);