bluera-knowledge 0.30.0 → 0.32.0

package/commands/add-folder.md

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

package/commands/add-repo.md

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

package/commands/cancel.md

@@ -0,0 +1,63 @@
+---
+description: Cancel a background job
+argument-hint: "[job-id]"
+allowed-tools: ["mcp__bluera-knowledge__execute"]
+---
+
+# Cancel Background Job
+
+Cancel a running or pending background job: **$ARGUMENTS**
+
+## Steps
+
+1. Parse the job ID from $ARGUMENTS (required)
+   - If no job ID provided, show error and suggest using /bluera-knowledge:check-status to list active jobs
+
+2. Use mcp__bluera-knowledge__execute tool with command "job:cancel":
+   - args.jobId: The job ID from $ARGUMENTS
+
+3. Display cancellation result:
+
+```
+✓ Job job_abc123def456 cancelled
+  Type: clone
+  Progress: 45% (was indexing)
+
+The job has been stopped and will not continue.
+```
+
+## When to Cancel
+
+Cancel a job when:
+- You accidentally started indexing the wrong repository
+- The operation is taking too long and you want to try a different approach
+- You need to free up system resources
+- You want to stop an operation before it completes
+
+## Important Notes
+
+- Only jobs in 'pending' or 'running' status can be cancelled
+- Completed or failed jobs cannot be cancelled
+- Cancelled jobs are marked with status 'cancelled' and remain in the job list
+- Partial work may be saved (e.g., partially indexed files remain in the database)
+
+## Error Handling
+
+If job cannot be cancelled:
+
+```
+✗ Cannot cancel job job_abc123def456: Job has already completed
+
+Only pending or running jobs can be cancelled.
+```
+
+If job not found:
+
+```
+✗ Job not found: job_abc123def456
+
+Common issues:
+- Check the job ID is correct
+- Use /bluera-knowledge:check-status to see all active jobs
+- Job may have already completed and been cleaned up
+```

package/commands/check-status.md

@@ -0,0 +1,130 @@
+---
+description: Check status of background operations
+argument-hint: "[job-id]"
+allowed-tools: ["mcp__bluera-knowledge__execute"]
+---
+
+# Check Background Job Status
+
+Check the status of a background operation: **$ARGUMENTS**
+
+## Steps
+
+1. Parse $ARGUMENTS:
+   - If a job ID is provided, use it for specific job status
+   - If no arguments, show all active jobs
+
+2. If job ID provided:
+   - Use mcp__bluera-knowledge__execute tool with command "job:status":
+     - args.jobId: The job ID from $ARGUMENTS
+   - Display current status, progress, and details
+
+3. If no job ID provided:
+   - Use mcp__bluera-knowledge__execute tool with command "jobs":
+     - args.activeOnly: true
+   - Display a table of running/pending jobs
+
+## Display Format
+
+For a specific job:
+
+```
+Job Status: job_abc123def456
+───────────────────────────────────────
+Store:    react-query
+Phase:    indexing (2/2)
+Progress: █████░░░ 45% (562/1,247 files)
+Started:  2 minutes ago
+```
+
+For all active jobs, format as a rich table with progress bars:
+
+```
+Active Background Jobs
+────────────────────────────────────────────────────────────────────────────────────────────
+| Job ID             | Store            | Phase           | Progress     | Files          |
+|--------------------|------------------|-----------------|--------------|----------------|
+| job_3abaf9639770   | claude-agent-sdk | indexing (2/2)  | ██████░░ 59% | 32/77 files    |
+| job_4f0315fdcff9   | zustand          | cloning (1/2)   | █░░░░░░░ 15% | -              |
+| job_1d1d93fd254f   | uvicorn          | indexing (1/1)  | ████░░░░ 44% | 20/100 files   |
+| job_ac7584576f18   | tanstack-query   | crawling (1/2)  | ███░░░░░ 31% | 24 pages       |
+| job_8113ea07cf53   | framer-motion    | indexing (2/2)  | ███░░░░░ 30% | 8/1378 files   |
+| job_288c24b6724c   | monaco-editor    | indexing (1/1)  | ███░░░░░ 31% | 12/924 files   |
+
+✓ tiktoken: Completed
+
+6 jobs still running. The smaller repos (claude-agent-sdk, zustand, uvicorn) are progressing
+faster. The larger ones (tanstack-query: 1741 files, framer-motion: 1378 files,
+monaco-editor: 924 files) will take longer.
+```
+
+**Phase column:**
+- Read from `job.details.phase`, `job.details.phaseStep`, `job.details.phaseTotalSteps`
+- Format as: `{phase} ({step}/{total})` e.g., `indexing (2/2)`, `cloning (1/2)`
+- Phases: `cloning`, `crawling`, `indexing`
+- Clone jobs: cloning (1/2) → indexing (2/2)
+- Index jobs: indexing (1/1)
+- Crawl jobs: crawling (1/2) → indexing (2/2)
+
+**Progress bar rendering (8 chars wide):**
+
+Build the bar using these characters: `█` (filled) and `░` (empty)
+
+```
+Algorithm:
+  filled = Math.round(progress / 100 * 8)
+  bar = '█'.repeat(filled) + '░'.repeat(8 - filled) + ' ' + progress + '%'
+```
+
+Examples:
+```
+  0% → ░░░░░░░░ 0%
+ 15% → █░░░░░░░ 15%
+ 25% → ██░░░░░░ 25%
+ 31% → ███░░░░░ 31%
+ 44% → ████░░░░ 44%
+ 59% → █████░░░ 59%
+ 75% → ██████░░ 75%
+ 88% → ███████░ 88%
+100% → ████████ 100%
+```
+
+**Files column:**
+- For indexing: Show `{filesProcessed}/{totalFiles} files` from job.details
+- For crawling: Show `{pagesCrawled} pages` from job.details
+- For cloning (phase 1): Show `-` (no file count yet)
+
+**Summary section:**
+- After the table, add a brief summary noting:
+  - How many jobs are still running
+  - Which repos are progressing faster (smaller file counts)
+  - Which repos will take longer (larger file counts)
+- If any jobs recently completed, note them with ✓ prefix
+
+If no active jobs:
+
+```
+No active background jobs.
+
+Recent completed jobs:
+────────────────────────────────────────────────────────────────────────────────────────────
+| Job ID             | Store            | Phase           | Files          | Completed    |
+|--------------------|------------------|-----------------|----------------|--------------|
+| job_old123abc456   | react-query      | indexing (2/2)  | 245/245 files  | 5m ago       |
+| job_xyz789ghi012   | zustand          | indexing (1/1)  | 67/67 files    | 12m ago      |
+
+All jobs completed successfully.
+```
+
+## Error Handling
+
+If job not found:
+
+```
+✗ Job not found: job_abc123def456
+
+Common issues:
+- Check the job ID is correct
+- Job may have expired (stale pending jobs are marked failed after 2 hours)
+- Use /bluera-knowledge:check-status to see all active jobs
+```

package/commands/crawl.md

@@ -0,0 +1,61 @@
+---
+description: Crawl web pages with natural language control and add to knowledge store
+argument-hint: "[url] [store-name] [--crawl instruction] [--extract instruction] [--fast]"
+allowed-tools: ["Bash(node ${CLAUDE_PLUGIN_ROOT}/dist/index.js crawl:*)"]
+context: fork
+---
+
+**⚠️ IMPORTANT: Store name is a POSITIONAL argument, NOT an option!**
+
+```
+WRONG: crawl https://example.com --store=my-store
+RIGHT: crawl https://example.com my-store
+```
+
+Crawling and indexing: $ARGUMENTS
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/dist/index.js crawl $ARGUMENTS
+```
+
+The web pages will be crawled with intelligent link selection and optional natural language extraction, then indexed for searching.
+
+**Note:** The web store is auto-created if it doesn't exist. No need to create the store first.
+
+## Usage Examples
+
+**Intelligent crawl strategy:**
+```
+/bluera-knowledge:crawl https://code.claude.com/docs/en/ claude-docs --crawl "all Getting Started pages"
+```
+
+**With extraction:**
+```
+/bluera-knowledge:crawl https://example.com/pricing pricing-store --extract "extract pricing and features"
+```
+
+**Both strategy and extraction:**
+```
+/bluera-knowledge:crawl https://docs.example.com my-docs --crawl "API reference pages" --extract "API endpoints and parameters"
+```
+
+**Simple BFS mode:**
+```
+/bluera-knowledge:crawl https://example.com/docs docs-store --simple
+```
+
+**Fast mode (axios-only, no JavaScript rendering):**
+```
+/bluera-knowledge:crawl https://example.com/docs docs-store --fast --max-pages 20
+```
+
+## Options
+
+- `--crawl <instruction>` - Natural language instruction for which pages to crawl (e.g., "all Getting Started pages")
+- `--extract <instruction>` - Natural language instruction for what content to extract (e.g., "extract API references")
+- `--simple` - Use simple BFS (breadth-first search) mode instead of intelligent crawling
+- `--max-pages <number>` - Maximum number of pages to crawl (default: 50)
+- `--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/doctor.md

@@ -0,0 +1,27 @@
+---
+description: Diagnose plugin issues and get fix instructions
+allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT:-.}/scripts/doctor.sh)"]
+---
+# Bluera Knowledge Doctor
+
+Run comprehensive diagnostics to identify and fix plugin issues.
+
+## Instructions
+
+Run the doctor script to check all prerequisites:
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT:-.}/scripts/doctor.sh"
+```
+
+The script checks:
+1. **Build tools** (make/gcc) - Required for native modules
+2. **Node.js** - Required for MCP server
+3. **Plugin dependencies** (node_modules) - Required for MCP server
+4. **MCP wrapper** - Required for MCP server startup
+5. **Python 3** - Optional, for embeddings
+6. **Playwright** - Optional, for web crawling
+
+For any `[FAIL]` items, follow the FIX instructions provided.
+
+After fixing issues, restart Claude Code for changes to take effect.

package/commands/eval.md

@@ -0,0 +1,222 @@
+---
+description: Evaluate agent quality across three modes — without BK, BK grep-only, and BK full
+argument-hint: "[query | --predefined | --predefined N]"
+allowed-tools: ["mcp__bluera-knowledge__execute", "mcp__bluera-knowledge__search", "mcp__bluera-knowledge__get_full_context", "Read", "Grep", "Glob", "WebSearch", "Bash"]
+context: fork
+---
+
+# Agent Quality Evaluation
+
+Compare how well Claude answers library questions across three access levels.
+
+For each query, three agents run in parallel:
+- **Without BK** — uses only web search and training knowledge
+- **BK Grep** — can Grep/Read/Glob the cloned source repos but has no vector search
+- **BK Full** — uses BK vector search + get_full_context + Grep/Read (all BK tools)
+
+Then score all three answers on accuracy, specificity, completeness, and source grounding.
+
+## Arguments
+
+Parse `$ARGUMENTS`:
+
+- **No arguments or empty**: Show usage help
+- **Quoted string** (not starting with `--`): Arbitrary query mode — run eval for that single question
+- **`--predefined`**: Run all predefined queries (skip any whose stores are not indexed)
+- **`--predefined N`**: Run predefined query #N only (1-based index)
+
+If no arguments provided, show:
+```
+Usage:
+  /bluera-knowledge:eval "How does Express handle errors?"     # Arbitrary query
+  /bluera-knowledge:eval --predefined                          # Run all predefined queries
+  /bluera-knowledge:eval --predefined 3                        # Run predefined query #3
+```
+
+## Step 1: Prerequisites Check
+
+1. Call MCP `execute` with `{ command: "stores" }` to list indexed stores
+2. If no stores are indexed, show error and abort:
+   ```
+   No knowledge stores indexed. Add at least one library first:
+     /bluera-knowledge:add-repo https://github.com/expressjs/express --name express
+   ```
+3. Record the list of available store names — you'll pass these to the BK Full agent
+4. Build a `STORE_PATHS` mapping from the store response: for each store with a `path` field, record `- **<name>**: \`<path>\`` (one per line, as a markdown list). This gets passed to the BK Grep agent.
+
+## Step 2: Resolve Queries
+
+### Predefined mode (`--predefined`)
+
+1. Read the predefined queries file: `$CLAUDE_PLUGIN_ROOT/evals/agent-quality/queries/predefined.yaml`
+2. Parse the YAML content
+3. For each query, check if ANY of its `store_hint` values match an available store name
+4. Split into **runnable** (store available) and **skipped** (store not available) lists
+5. If `--predefined N` was specified, select only query at index N from the full list (skip if store not available)
+6. If no queries are runnable, show what stores to add and abort
+
+### Arbitrary mode (bare query string)
+
+1. Use the raw query string as the question
+2. Set `expected_topics` and `anti_patterns` to empty lists
+3. Set `id` to "arbitrary", `category` to "general", `difficulty` to "unknown"
+
+## Step 3: Load Templates
+
+Read these files from `$CLAUDE_PLUGIN_ROOT/evals/agent-quality/templates/`:
+
+1. `without-bk-agent.md` — instructions for the baseline agent
+2. `bk-grep-agent.md` — instructions for the BK Grep agent
+3. `with-bk-agent.md` — instructions for the BK Full agent
+4. `judge.md` — grading rubric
+
+## Step 4: Run Eval (for each query)
+
+### Spawn ALL THREE agents in parallel (same turn, three Task tool calls)
+
+**Without-BK agent** — Use the Task tool with `subagent_type: "general-purpose"`:
+- Take the content from `without-bk-agent.md`
+- Replace `{{QUESTION}}` with the actual question
+- Send as the task prompt
+
+**BK Grep agent** — Use the Task tool with `subagent_type: "general-purpose"`:
+- Take the content from `bk-grep-agent.md`
+- Replace `{{QUESTION}}` with the actual question
+- Replace `{{STORE_PATHS}}` with the store name-to-path mapping built in Step 1
+- Send as the task prompt
+
+**BK Full agent** — Use the Task tool with `subagent_type: "general-purpose"`:
+- Take the content from `with-bk-agent.md`
+- Replace `{{QUESTION}}` with the actual question
+- Replace `{{STORES}}` with the list of available store names (one per line, as a markdown list)
+- Send as the task prompt
+
+Wait for all three agents to complete.
+
+### Capture Token Usage
+
+From each Task tool response, parse the `<usage>` block to extract:
+- `total_tokens` — the total tokens consumed by the agent
+- `duration_ms` — wall-clock time for the agent
+
+If usage data is not available in a Task response, show "N/A" for that agent.
+
+### Judge the results
+
+Using the rubric from `judge.md`, evaluate all three answers yourself:
+
+1. Read all three agent responses
+2. For each answer, score all 4 criteria (1-5):
+   - **Factual Accuracy**: Are the claims correct?
+   - **Specificity**: Does it cite specific files, functions, code?
+   - **Completeness**: Does it cover the full answer?
+   - **Source Grounding**: Are claims backed by evidence?
+3. If the query has `expected_topics`, check which answers mention each topic
+4. If the query has `anti_patterns`, flag if any answer makes those claims
+5. Calculate totals (max 20 each), determine winner and deltas
+
+## Step 5: Output Results
+
+### Single query output (arbitrary or `--predefined N`)
+
+Show the full comparison:
+
+```
+## Eval: "<question>"
+
+| Criterion         | Without BK | BK Grep | BK Full |
+|-------------------|:----------:|:-------:|:-------:|
+| Accuracy          |     X      |    X    |    X    |
+| Specificity       |     X      |    X    |    X    |
+| Completeness      |     X      |    X    |    X    |
+| Source Grounding   |     X      |    X    |    X    |
+| **Total**         |   **X**    |  **X**  |  **X**  |
+
+| Usage             | Without BK | BK Grep | BK Full |
+|-------------------|:----------:|:-------:|:-------:|
+| Tokens            |   X,XXX    |  X,XXX  |  X,XXX  |
+| Duration (s)      |    X.X     |   X.X   |   X.X   |
+
+**Winner:** [BK Full | BK Grep | Without BK | Tie] ([significant | marginal | none])
+**Key Difference:** [One sentence explaining the most important quality gap]
+**Grep vs Full:** [One sentence on whether vector search outperformed manual grep, and if so how]
+```
+
+If expected topics were provided:
+```
+### Expected Topics
+- [x] topic covered by all three
+- [x] topic covered by BK Full + BK Grep only
+- [x] topic covered by BK Full only
+- [ ] topic missed by all
+```
+
+### Multi-query output (`--predefined`)
+
+Show a summary row per query, then aggregate:
+
+```
+## Agent Quality Eval Summary
+
+Ran X/8 queries (Y skipped — stores not indexed)
+
+| # | Query | Difficulty | w/o BK | Grep | Full | Winner | Delta |
+|---|-------|:----------:|:------:|:----:|:----:|--------|-------|
+| 1 | query-id | medium | 9/20 | 15/20 | 19/20 | Full | significant |
+| 2 | query-id | easy | 14/20 | 17/20 | 18/20 | Full | marginal |
+| ... |
+
+### Token Usage
+
+| # | Query | w/o BK tokens | Grep tokens | Full tokens |
+|---|-------|:-------------:|:-----------:|:-----------:|
+| 1 | query-id | 2,340 | 8,120 | 5,670 |
+| 2 | query-id | 1,890 | 6,450 | 4,230 |
+| ... |
+
+### Aggregate
+- **Without BK mean:** X.X/20 (avg X,XXX tokens)
+- **BK Grep mean:** X.X/20 (avg X,XXX tokens)
+- **BK Full mean:** X.X/20 (avg X,XXX tokens)
+- **Full vs Without:** +X.X points (+XX%)
+- **Full vs Grep:** +X.X points (+XX%)
+- **Grep vs Without:** +X.X points (+XX%)
+- **Full win rate:** X/X (XX%)
+- **Significant wins (Full):** X
+
+### By Category
+| Category | w/o BK | Grep | Full | Full delta |
+|----------|:------:|:----:|:----:|------------|
+| implementation | X.X | X.X | X.X | +X.X |
+| api | X.X | X.X | X.X | +X.X |
+
+### By Difficulty
+| Difficulty | w/o BK | Grep | Full | Full delta |
+|------------|:------:|:----:|:----:|------------|
+| easy | X.X | X.X | X.X | +X.X |
+| medium | X.X | X.X | X.X | +X.X |
+| hard | X.X | X.X | X.X | +X.X |
+
+### Token Efficiency
+| Agent | Mean Score | Mean Tokens | Score/1K Tokens |
+|-------|:----------:|:-----------:|:---------------:|
+| Without BK | X.X | X,XXX | X.XX |
+| BK Grep | X.X | X,XXX | X.XX |
+| BK Full | X.X | X,XXX | X.XX |
+```
+
+If any queries were skipped:
+```
+### Skipped (store not indexed)
+- vue-reactivity-tracking — add with: /bluera-knowledge:add-repo https://github.com/vuejs/core --name vue
+- fastapi-dependency-injection — add with: /bluera-knowledge:add-repo https://github.com/fastapi/fastapi --name fastapi
+```
+
+## Important Notes
+
+- Each query spawns 3 subagents. For `--predefined` with 8 queries, that's up to 24 agent runs. Process one query at a time (but spawn all three agents for each query in parallel).
+- The without-BK agent may use WebSearch — this is intentional. We're comparing against "the best Claude can do without BK."
+- The BK Grep agent may NOT use WebSearch. It tests what an agent can discover by exploring raw source code, to isolate the value of vector search.
+- Scoring is somewhat subjective. The value is in the comparison (relative scores) rather than absolute numbers. Look at the delta and key differences.
+- The Token Efficiency table reveals cost-effectiveness: if BK Grep achieves similar scores to BK Full with fewer tokens, it suggests vector search isn't adding much for that query type.
+- For arbitrary queries without expected topics, grading relies entirely on the 4 general criteria. This is fine — it still reveals whether BK adds value.

package/commands/health.md

@@ -0,0 +1,72 @@
+---
+description: Check health of all stores (path existence, model compatibility)
+allowed-tools: ["mcp__bluera-knowledge__execute"]
+---
+
+# Store Health Check
+
+Diagnose issues with knowledge stores: missing paths, schema migrations, model mismatches.
+
+## Steps
+
+1. Use the mcp__bluera-knowledge__execute tool with command "stores:health" to check all stores
+
+2. Present results grouped by status:
+
+```
+## Store Health Report
+
+### Errors (require action)
+| Store | Type | Issue | Fix |
+|-------|------|-------|-----|
+| my-repo | repo | Path not found | Re-create store or fix projectRoot |
+
+### Warnings (recommended action)
+| Store | Type | Issue | Fix |
+|-------|------|-------|-----|
+| old-docs | web | Schema v1 | Run: /bluera-knowledge:index old-docs |
+
+### Healthy
+- react-docs (web)
+- lodash (repo)
+
+**Summary**: 2 healthy, 1 warning, 1 error
+```
+
+## Exit Codes
+
+The health check returns an exit code for scripting:
+
+| Exit Code | Meaning |
+|-----------|---------|
+| 0 | All stores healthy |
+| 1 | At least one store has an error (path not found) |
+| 2 | No errors, but at least one warning (model/schema issue) |
+
+## Issue Types
+
+### PATH_NOT_FOUND (Error)
+The store's source path no longer exists. This happens when:
+- A local folder was deleted or moved
+- The project was relocated and paths weren't updated
+- A cloned repo directory was removed
+
+**Fix**: Re-create the store or update the projectRoot setting.
+
+### SCHEMA_V1 (Warning)
+The store was created before model tracking was added. It needs to be re-indexed to be searchable.
+
+**Fix**: Run `/bluera-knowledge:index <store-name>`
+
+### MODEL_MISMATCH (Warning)
+The store was indexed with a different embedding model than the current configuration.
+
+**Fix**: Run `/bluera-knowledge:index <store-name>` to re-index with the current model.
+
+## Check Single Store
+
+To check a specific store only:
+
+```
+stores:health --store=<store-name>
+```