bluera-knowledge 0.31.0 → 0.33.0

package/skills/sync/SKILL.md

@@ -0,0 +1,96 @@
+---
+description: Sync stores from definitions config (bootstrap on fresh clone)
+allowed-tools: ["mcp__bluera-knowledge__execute"]
+---
+
+# Sync Stores from Definitions
+
+Sync stores from the git-committable definitions config. This is useful when:
+- You've cloned a repo that has `.bluera/bluera-knowledge/stores.config.json`
+- You want to recreate all stores defined by the team
+- You want to check for orphan stores not in the config
+
+## Steps
+
+1. Use the mcp__bluera-knowledge__execute tool with command "stores:sync" to sync stores from definitions
+
+   Optional arguments:
+   - `dryRun: true` - Show what would happen without making changes
+   - `prune: true` - Remove stores not in definitions
+   - `reindex: true` - Re-index existing stores after sync
+
+2. Present results in a structured format:
+
+```
+## Sync Results
+
+**Created**: 3 stores
+- my-docs (file)
+- react-source (repo)
+- api-docs (web)
+
+**Skipped** (already exist): 2 stores
+- lodash
+- typescript-docs
+
+**Orphans** (not in definitions): 1 store
+- old-unused-store
+
+No errors occurred.
+```
+
+## Dry Run Mode
+
+When using dry run, show what WOULD happen:
+
+```
+## Sync Preview (Dry Run)
+
+**Would create**: 3 stores
+- my-docs (file)
+- react-source (repo)
+- api-docs (web)
+
+**Would skip** (already exist): 2 stores
+- lodash
+- typescript-docs
+
+**Orphans** (not in definitions): 1 store
+- old-unused-store
+
+To apply these changes, run without --dry-run
+```
+
+## If No Definitions Found
+
+If no store definitions config exists:
+
+```
+## No Store Definitions Found
+
+The config file `.bluera/bluera-knowledge/stores.config.json` doesn't exist yet.
+
+Store definitions are automatically created when you:
+- Add a repo: `/bluera-knowledge:add-repo <url>`
+- Add a folder: `/bluera-knowledge:add-folder <path>`
+- Crawl a website: `/bluera-knowledge:crawl <url>`
+
+The config file will be created automatically and can be committed to git for team sharing.
+```
+
+## Error Handling
+
+If some stores fail to sync, report them individually:
+
+```
+## Sync Results
+
+**Created**: 2 stores
+- my-docs
+- api-docs
+
+**Failed**: 1 store
+- react-source: Directory does not exist: /path/to/repo
+
+Continue to resolve the errors manually.
+```

package/skills/test-plugin/SKILL.md

@@ -0,0 +1,547 @@
+---
+description: Run comprehensive plugin validation test suite
+argument-hint: "[--dev]"
+context: fork
+---
+
+# Test Plugin
+
+Comprehensive test of all Bluera Knowledge plugin functionality covering the **full API surface**.
+
+## API Coverage
+
+| Category | Tests |
+|----------|-------|
+| MCP execute commands | help, commands, stores, store:create, store:info, store:index, store:delete, stores:health, stores:check-models, stores:sync, stores:pull, jobs, job:status, job:cancel |
+| MCP tools | search, get_full_context |
+| Slash commands | stores, search, suggest, check-status, skill-activation, index, add-folder, health, sync |
+| Web crawling | crawl (start job, verify status, cancel) |
+| Hooks | PostToolUse, UserPromptSubmit, SessionStart |
+
+## When to Use Each Mode
+
+| Scenario | Command | Tests |
+|----------|---------|-------|
+| Claude running with `--plugin-dir .` | `/test-plugin` | 38/38 (full suite) |
+| Plugin installed from marketplace | `/test-plugin` | 38/38 (full suite) |
+| Claude running WITHOUT plugin loaded | `/test-plugin --dev` | 29/38 (no slash cmds) |
+
+**Modes:**
+- **Default mode**: Uses Claude's MCP tools. Runs all 38 tests including slash commands.
+- **`--dev` mode**: Spawns MCP server directly. Skips slash command tests since they require Claude's skill router.
+
+## Context
+
+!`echo "=== BK Plugin Test ===" && ls -la .bluera/bluera-knowledge/ 2>/dev/null || echo "No BK data dir yet (will be created)"`
+
+## Mode Detection
+
+Check if `--dev` flag is present in: $ARGUMENTS
+
+- If `--dev` is present: Use **Development Mode**
+- Otherwise: Use **Production Mode**
+
+---
+
+## Pre-Test Cleanup
+
+Clean up any leftover artifacts from previous test runs (ignore errors):
+
+**In `--dev` mode:**
+```bash
+node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-test-store"}}' 2>/dev/null || true
+node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-test-folder"}}' 2>/dev/null || true
+node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-crawl-test"}}' 2>/dev/null || true
+rm -rf .bluera/bluera-knowledge/test-content
+```
+
+**In production mode:**
+1. Call MCP `execute` with `{ command: "store:delete", args: { store: "bk-test-store" } }` - ignore errors
+2. Call MCP `execute` with `{ command: "store:delete", args: { store: "bk-test-folder" } }` - ignore errors
+3. Call MCP `execute` with `{ command: "store:delete", args: { store: "bk-crawl-test" } }` - ignore errors
+4. Run: `rm -rf .bluera/bluera-knowledge/test-content`
+
+## Test Content Setup
+
+Create test content for indexing:
+
+```bash
+mkdir -p .bluera/bluera-knowledge/test-content
+cat > .bluera/bluera-knowledge/test-content/test-file.md << 'EOF'
+# BK Plugin Test File
+
+This file contains unique test content for validating the Bluera Knowledge plugin.
+
+## Test Function
+
+The `validateBKPlugin` function performs comprehensive testing of all plugin features.
+It checks MCP connectivity, store operations, search functionality, and cleanup.
+
+Keywords: bluera-knowledge-test, plugin-validation, mcp-test
+EOF
+```
+
+---
+
+# PRODUCTION MODE (default)
+
+Use this section if `--dev` flag is NOT present.
+
+## Part 1: MCP Execute Commands
+
+1. **help**: Call `execute` with `{ command: "help" }`
+   - PASS if response contains "Available commands"
+
+2. **commands**: Call `execute` with `{ command: "commands" }`
+   - PASS if response contains array of commands including ALL of: "stores", "store:create", "store:info", "store:index", "store:delete", "stores:pull", "stores:check-models", "stores:health", "stores:sync", "jobs", "job:status", "job:cancel", "help", "commands", "uninstall"
+
+3. **stores**: Call `execute` with `{ command: "stores" }`
+   - PASS if no error (may return empty array)
+
+4. **store:create**: Call `execute` with:
+   ```json
+   { "command": "store:create", "args": { "name": "bk-test-store", "type": "file", "source": ".bluera/bluera-knowledge/test-content" } }
+   ```
+   - PASS if response indicates success and contains store id
+
+5. **store:info**: Call `execute` with:
+   ```json
+   { "command": "store:info", "args": { "store": "bk-test-store" } }
+   ```
+   - PASS if response contains store name and type
+
+6. **store:index**: Call `execute` with:
+   ```json
+   { "command": "store:index", "args": { "store": "bk-test-store" } }
+   ```
+   - PASS if response indicates indexing started (job created)
+
+7. **jobs**: Call `execute` with `{ command: "jobs" }`
+   - PASS if response contains jobs array (may be empty if indexing completed)
+
+8. **job:status** (if job from step 6 available): Call `execute` with:
+   ```json
+   { "command": "job:status", "args": { "jobId": "<job-id-from-step-6>" } }
+   ```
+   - PASS if response contains job status (pending, running, or completed)
+   - SKIP if no job id available (indexing was synchronous)
+
+9. **stores:health**: Call `execute` with `{ command: "stores:health" }`
+   - PASS if response contains health data (no error thrown)
+
+10. **stores:check-models**: Call `execute` with `{ command: "stores:check-models" }`
+    - PASS if response contains model compatibility info (no error thrown)
+
+11. **stores:sync** (dry run): Call `execute` with:
+    ```json
+    { "command": "stores:sync", "args": { "dryRun": true } }
+    ```
+    - PASS if response contains sync result with skipped/orphans arrays
+
+12. **stores:pull** (error case): Call `execute` with:
+    ```json
+    { "command": "stores:pull", "args": { "store": "bk-test-store" } }
+    ```
+    - PASS if response contains error about non-repo store (bk-test-store is type "file", not "repo")
+
+## Part 2: MCP Search Tools
+
+13. **search**: Call MCP tool `search` with:
+    ```json
+    { "query": "validateBKPlugin", "stores": ["bk-test-store"] }
+    ```
+    - PASS if results array is non-empty
+
+14. **get_full_context**: Call MCP tool `get_full_context` with resultId from step 13
+    - PASS if response contains code or documentation content
+
+## Part 3: Slash Commands
+
+15. **/stores**: Run `/bluera-knowledge:stores`
+    - PASS if bk-test-store is listed
+
+16. **/search**: Run `/bluera-knowledge:search "bluera-knowledge-test"`
+    - PASS if results are shown
+
+17. **/suggest**: Run `/bluera-knowledge:suggest`
+    - PASS if no error thrown
+
+18. **/check-status**: Run `/bluera-knowledge:check-status`
+    - PASS if shows job status (may show "no active jobs")
+
+19. **/skill-activation**: Run `/bluera-knowledge:skill-activation`
+    - PASS if shows activation configuration or prompts for setup
+
+20. **/index**: Run `/bluera-knowledge:index bk-test-store`
+    - PASS if indexing completes or starts successfully
+
+21. **/add-folder**: Run `/bluera-knowledge:add-folder .bluera/bluera-knowledge/test-content --name bk-test-folder`
+    - PASS if store creation starts or completes
+
+22. **/health**: Run `/bluera-knowledge:health`
+    - PASS if shows health report (no error thrown)
+
+23. **/sync**: Run `/bluera-knowledge:sync --dry-run`
+    - PASS if shows sync preview (dry run, no side effects)
+
+## Part 4: Web Crawl Testing
+
+> **Note:** Web crawl functionality requires the CLI (`bluera-knowledge crawl`). MCP `store:create` only supports `file` and `repo` types. Skip this section if testing MCP-only environments.
+
+24. **Create web store via CLI** (requires CLI access):
+    ```bash
+    bluera-knowledge crawl https://httpbin.org/html bk-crawl-test --max-pages 1
+    ```
+    - PASS if crawl completes and store is created
+    - SKIP if CLI not available
+
+25. **Verify store exists**: Call `execute` with `{ command: "stores" }`
+    - PASS if bk-crawl-test appears in store list
+    - SKIP if test 24 was skipped
+
+26. **job:cancel** (if crawl job still running): Call `execute` with:
+    ```json
+    { "command": "job:cancel", "args": { "jobId": "<crawl-job-id>" } }
+    ```
+    - PASS if cancelled or already completed
+    - SKIP if test 24 was skipped
+
+27. **Delete crawl store**: Call `execute` with:
+    ```json
+    { "command": "store:delete", "args": { "store": "bk-crawl-test" } }
+    ```
+    - PASS if deletion succeeds
+    - SKIP if test 24 was skipped
+
+## Part 5: Hook Tests
+
+> **Note:** All hook tests use `$CLAUDE_PLUGIN_ROOT` to locate the plugin's hooks directory. This variable is set automatically by Claude Code when running plugin skills.
+
+28. **Hook Registration**:
+    ```bash
+    jq -e '(.hooks.PostToolUse | length) > 0 and (.hooks.UserPromptSubmit | length) > 0 and (.hooks.SessionStart | length) > 0' "$CLAUDE_PLUGIN_ROOT/hooks/hooks.json"
+    ```
+    - PASS if returns `true`
+
+29. **PostToolUse Hook - Library Detection**:
+    ```bash
+    echo '{"tool_name": "Read", "tool_input": {"file_path": "/project/node_modules/express/index.js"}}' | python3 "$CLAUDE_PLUGIN_ROOT/hooks/posttooluse-bk-reminder.py"
+    ```
+    - PASS if output contains "BLUERA-KNOWLEDGE REMINDER"
+
+30. **PostToolUse Hook - Non-Library**:
+    ```bash
+    echo '{"tool_name": "Read", "tool_input": {"file_path": "/project/src/index.ts"}}' | python3 "$CLAUDE_PLUGIN_ROOT/hooks/posttooluse-bk-reminder.py"
+    ```
+    - PASS if output is empty
+
+31. **Skill Activation Hook - Matching**:
+    ```bash
+    echo '{"prompt": "why does the express package throw this error?"}' | python3 "$CLAUDE_PLUGIN_ROOT/hooks/skill-activation.py"
+    ```
+    - PASS if output contains "MANDATORY EVALUATION"
+
+32. **Skill Activation Hook - Excluded**:
+    ```bash
+    echo '{"prompt": "/bluera-knowledge:search express"}' | python3 "$CLAUDE_PLUGIN_ROOT/hooks/skill-activation.py"
+    ```
+    - PASS if output is empty
+
+33. **Skill Rules File**:
+    ```bash
+    jq -e '(.skills | length) > 0 and (.globalExclusions | length) > 0' "$CLAUDE_PLUGIN_ROOT/hooks/skill-rules.json"
+    ```
+    - PASS if returns `true`
+
+## Part 6: Cleanup
+
+34. **Delete test store**: Call `execute` with:
+    ```json
+    { "command": "store:delete", "args": { "store": "bk-test-store" } }
+    ```
+    - PASS if deletion succeeds
+
+35. **Delete test folder store**: Call `execute` with:
+    ```json
+    { "command": "store:delete", "args": { "store": "bk-test-folder" } }
+    ```
+    - PASS if deletion succeeds or store doesn't exist (created only in production mode by /add-folder)
+
+36. **Remove test content**:
+    ```bash
+    rm -rf .bluera/bluera-knowledge/test-content
+    ```
+    - PASS if command succeeds
+
+37. **Verify store cleanup**: Call `execute` with `{ command: "stores" }`
+    - PASS if bk-test-store and bk-test-folder are NOT in the list
+
+38. **Verify no test artifacts**:
+    ```bash
+    test ! -d .bluera/bluera-knowledge/test-content && echo "clean"
+    ```
+    - PASS if outputs "clean"
+
+---
+
+# DEVELOPMENT MODE (`--dev`)
+
+Use this section if `--dev` flag is present. Uses `scripts/test-mcp-dev.js`.
+
+### Part 1: MCP Commands (via dev script)
+
+1. **help**:
+   ```bash
+   node scripts/test-mcp-dev.js call execute '{"command":"help"}'
+   ```
+   - PASS if contains "Available commands"
+
+2. **commands**:
+   ```bash
+   node scripts/test-mcp-dev.js call execute '{"command":"commands"}'
+   ```
+   - PASS if contains commands array including all 15 commands
+
+3. **stores**:
+   ```bash
+   node scripts/test-mcp-dev.js call execute '{"command":"stores"}'
+   ```
+   - PASS if no error
+
+4. **store:create**:
+   ```bash
+   node scripts/test-mcp-dev.js call execute '{"command":"store:create","args":{"name":"bk-test-store","type":"file","source":".bluera/bluera-knowledge/test-content"}}'
+   ```
+   - PASS if success
+
+5. **store:info**:
+   ```bash
+   node scripts/test-mcp-dev.js call execute '{"command":"store:info","args":{"store":"bk-test-store"}}'
+   ```
+   - PASS if contains store details
+
+6. **store:index**:
+   ```bash
+   node scripts/test-mcp-dev.js call execute '{"command":"store:index","args":{"store":"bk-test-store"}}'
+   ```
+   - PASS if indexing starts
+
+7. **jobs**:
+   ```bash
+   node scripts/test-mcp-dev.js call execute '{"command":"jobs"}'
+   ```
+   - PASS if returns jobs array
+
+8. **job:status** (if job available):
+   ```bash
+   node scripts/test-mcp-dev.js call execute '{"command":"job:status","args":{"jobId":"<job-id>"}}'
+   ```
+   - PASS if returns status
+
+9. **stores:health**:
+   ```bash
+   node scripts/test-mcp-dev.js call execute '{"command":"stores:health"}'
+   ```
+   - PASS if returns health data
+
+10. **stores:check-models**:
+    ```bash
+    node scripts/test-mcp-dev.js call execute '{"command":"stores:check-models"}'
+    ```
+    - PASS if returns model compatibility info
+
+11. **stores:sync** (dry run):
+    ```bash
+    node scripts/test-mcp-dev.js call execute '{"command":"stores:sync","args":{"dryRun":true}}'
+    ```
+    - PASS if returns sync result with skipped/orphans
+
+12. **stores:pull** (error case):
+    ```bash
+    node scripts/test-mcp-dev.js call execute '{"command":"stores:pull","args":{"store":"bk-test-store"}}'
+    ```
+    - PASS if returns error about non-repo store
+
+### Part 2: Search (via dev script)
+
+13-14. **Search + Get Full Context**:
+   ```bash
+   node scripts/test-mcp-dev.js session << 'EOF'
+search {"query":"validateBKPlugin","stores":["bk-test-store"]}
+get_full_context {"resultId":"$LAST_ID"}
+EOF
+   ```
+   - PASS if search returns results and context contains content
+
+### Part 3: Slash Commands (SKIPPED in --dev mode)
+
+Tests 15-23 are skipped - slash commands require Claude's skill router.
+
+### Part 4: Web Crawl (via dev script)
+
+24. **Create crawl store**:
+    ```bash
+    node scripts/test-mcp-dev.js call execute '{"command":"store:create","args":{"name":"bk-crawl-test","type":"web","source":"https://httpbin.org/html","options":{"maxPages":1}}}'
+    ```
+    - PASS if returns job id
+
+25. **Verify crawl job**:
+    ```bash
+    node scripts/test-mcp-dev.js call execute '{"command":"jobs"}'
+    ```
+    - PASS if job appears
+
+26. **job:cancel** (if running):
+    ```bash
+    node scripts/test-mcp-dev.js call execute '{"command":"job:cancel","args":{"jobId":"<crawl-job-id>"}}'
+    ```
+    - PASS if cancelled or completed
+
+27. **Delete crawl store**:
+    ```bash
+    node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-crawl-test"}}'
+    ```
+    - PASS if deleted
+
+### Part 5: Hook Tests
+
+> **Note:** In dev mode, set `CLAUDE_PLUGIN_ROOT` to the current directory (plugin source).
+
+28. **Hook Registration**:
+    ```bash
+    jq -e '(.hooks.PostToolUse | length) > 0 and (.hooks.UserPromptSubmit | length) > 0 and (.hooks.SessionStart | length) > 0' hooks/hooks.json
+    ```
+    - PASS if returns `true`
+
+29. **PostToolUse Hook - Library Detection**:
+    ```bash
+    echo '{"tool_name": "Read", "tool_input": {"file_path": "/project/node_modules/express/index.js"}}' | python3 hooks/posttooluse-bk-reminder.py
+    ```
+    - PASS if output contains "BLUERA-KNOWLEDGE REMINDER"
+
+30. **PostToolUse Hook - Non-Library**:
+    ```bash
+    echo '{"tool_name": "Read", "tool_input": {"file_path": "/project/src/index.ts"}}' | python3 hooks/posttooluse-bk-reminder.py
+    ```
+    - PASS if output is empty
+
+31. **Skill Activation Hook - Matching**:
+    ```bash
+    CLAUDE_PLUGIN_ROOT="$(pwd)" && echo '{"prompt": "why does the express package throw this error?"}' | python3 hooks/skill-activation.py
+    ```
+    - PASS if output contains "MANDATORY EVALUATION"
+
+32. **Skill Activation Hook - Excluded**:
+    ```bash
+    CLAUDE_PLUGIN_ROOT="$(pwd)" && echo '{"prompt": "/bluera-knowledge:search express"}' | python3 hooks/skill-activation.py
+    ```
+    - PASS if output is empty
+
+33. **Skill Rules File**:
+    ```bash
+    jq -e '(.skills | length) > 0 and (.globalExclusions | length) > 0' hooks/skill-rules.json
+    ```
+    - PASS if returns `true`
+
+### Part 6: Cleanup (via dev script)
+
+34. **Delete test store**:
+    ```bash
+    node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-test-store"}}'
+    ```
+    - PASS if deleted
+
+35. **Delete test folder store**:
+    ```bash
+    node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-test-folder"}}' 2>/dev/null || true
+    ```
+    - PASS if deleted or doesn't exist
+
+36. **Remove test content**:
+    ```bash
+    rm -rf .bluera/bluera-knowledge/test-content
+    ```
+    - PASS if command succeeds
+
+37. **Verify store cleanup**:
+    ```bash
+    node scripts/test-mcp-dev.js call execute '{"command":"stores"}'
+    ```
+    - PASS if bk-test-store and bk-test-folder are NOT in the list
+
+38. **Verify no test artifacts**:
+    ```bash
+    test ! -d .bluera/bluera-knowledge/test-content && echo "clean"
+    ```
+    - PASS if outputs "clean"
+
+---
+
+## Output Format
+
+### Production mode (38 tests):
+
+| # | Test | Status |
+|---|------|--------|
+| 1 | MCP help | ? |
+| 2 | MCP commands (all 15) | ? |
+| 3 | MCP stores | ? |
+| 4 | MCP store:create | ? |
+| 5 | MCP store:info | ? |
+| 6 | MCP store:index | ? |
+| 7 | MCP jobs | ? |
+| 8 | MCP job:status | ? |
+| 9 | MCP stores:health | ? |
+| 10 | MCP stores:check-models | ? |
+| 11 | MCP stores:sync (dry) | ? |
+| 12 | MCP stores:pull (error) | ? |
+| 13 | MCP search | ? |
+| 14 | MCP get_full_context | ? |
+| 15 | /stores | ? |
+| 16 | /search | ? |
+| 17 | /suggest | ? |
+| 18 | /check-status | ? |
+| 19 | /skill-activation | ? |
+| 20 | /index | ? |
+| 21 | /add-folder | ? |
+| 22 | /health | ? |
+| 23 | /sync | ? |
+| 24 | Crawl store create | ? |
+| 25 | Crawl job verify | ? |
+| 26 | Crawl job:cancel | ? |
+| 27 | Crawl store delete | ? |
+| 28 | Hook registration | ? |
+| 29 | PostToolUse - library | ? |
+| 30 | PostToolUse - non-library | ? |
+| 31 | Skill activation - match | ? |
+| 32 | Skill activation - exclude | ? |
+| 33 | Skill rules file | ? |
+| 34 | Delete test store | ? |
+| 35 | Delete test folder store | ? |
+| 36 | Remove test content | ? |
+| 37 | Verify store cleanup | ? |
+| 38 | Verify no artifacts | ? |
+
+**Result: X/38 tests passed**
+
+### Development mode (29 tests):
+
+Same table but tests 15-23 show "SKIPPED (--dev mode)"
+
+**Result: X/29 tests passed (9 skipped)**
+
+---
+
+## Error Recovery
+
+If tests fail partway through, clean up manually:
+
+```bash
+# Delete test stores
+node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-test-store"}}' 2>/dev/null || true
+node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-test-folder"}}' 2>/dev/null || true
+node scripts/test-mcp-dev.js call execute '{"command":"store:delete","args":{"store":"bk-crawl-test"}}' 2>/dev/null || true
+
+# Remove test content
+rm -rf .bluera/bluera-knowledge/test-content
+```

package/skills/uninstall/SKILL.md

@@ -0,0 +1,65 @@
+---
+description: Remove Bluera Knowledge data from this project
+allowed-tools: ["mcp__bluera-knowledge__execute"]
+---
+
+# Uninstall Bluera Knowledge
+
+Remove Bluera Knowledge data from this project.
+
+## Steps
+
+1. Use mcp__bluera-knowledge__execute tool with command "uninstall":
+   - Optional args.global: true to also remove global data
+   - Optional args.keepDefinitions: false to also remove stores.config.json
+
+2. Display the result showing what was deleted and cleanup instructions.
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `global` | Also delete global data (~/.local/share/bluera-knowledge/) |
+| `keepDefinitions` | Keep stores.config.json for team sharing (default: true) |
+
+## Examples
+
+**Clean project data (preserves stores.config.json):**
+```
+/bluera-knowledge:uninstall
+```
+
+**Full cleanup including store definitions:**
+```
+Use uninstall with keepDefinitions: false
+```
+
+**Full cleanup including global data:**
+```
+Use uninstall with global: true
+```
+
+## What Gets Deleted
+
+**Project data** (`.bluera/bluera-knowledge/`):
+- `data/` - Vector indices, cloned repos, stores.json
+- `config.json` - Plugin configuration
+- `stores.config.json` - Only if keepDefinitions: false
+
+**Global data** (with --global flag):
+- `~/.local/share/bluera-knowledge/` - Job history, skill settings
+
+## What Is NOT Deleted
+
+- **Plugin cache** - Managed by Claude Code, instructions provided
+- **Python venv** - Inside plugin cache, cleaned when cache is cleared
+
+## Testing Fresh Plugin Installs
+
+After running uninstall, to test a completely fresh plugin install:
+
+1. Exit Claude Code
+2. Clear plugin cache: `rm -rf ~/.claude/plugins/cache/bluera-knowledge-*`
+3. Restart Claude Code and reinstall the plugin
+
+_Clearing the plugin cache removes everything: plugin code, Python venv, and all dependencies._