magector 1.4.3 → 1.5.1

package/README.md

@@ -1,8 +1,8 @@
 # Magector
 
-**Semantic code search engine for Magento 2 and Adobe Commerce, powered by ONNX embeddings and HNSW vector search.**
+**Technology-aware MCP server for Magento 2 and Adobe Commerce with intelligent indexing and search.**
 
-Magector indexes an entire Magento 2 or Adobe Commerce codebase and lets you search it with natural language. Instead of grepping for keywords, ask questions like *"how are checkout totals calculated?"* or *"where is the product price determined?"* and get ranked, relevant results in under 50ms.
+Magector is a Model Context Protocol (MCP) server that deeply understands Magento 2 and Adobe Commerce. It builds a semantic vector index of your entire codebase — 18,000+ files across hundreds of modules — and exposes 21 tools that let AI assistants search, navigate, and understand the code with domain-specific intelligence. Instead of grepping for keywords, your AI asks *"how are checkout totals calculated?"* and gets ranked, relevant results in under 50ms, enriched with Magento pattern detection (plugins, observers, controllers, DI preferences, layout XML, and 20+ more).
 
 [![Rust](https://img.shields.io/badge/rust-1.75+-orange.svg)](https://www.rust-lang.org)
 [![Node.js](https://img.shields.io/badge/node-18+-green.svg)](https://nodejs.org)
@@ -15,38 +15,26 @@ Magector indexes an entire Magento 2 or Adobe Commerce codebase and lets you sea
 
 ## Why Magector
 
-Magento 2 and Adobe Commerce have **18,000+ source files** across hundreds of modules. Finding the right code is slow:
+Magento 2 and Adobe Commerce have **18,000+ PHP, XML, JS, PHTML, and GraphQL files** spread across hundreds of modules. The codebase relies heavily on indirection — plugins intercept methods defined in other modules, observers react to events dispatched elsewhere, `di.xml` rewires interfaces to concrete classes, and layout XML stitches blocks and templates together. No single file tells the full story.
 
-| Approach | Finds semantic matches | Understands Magento patterns | Speed (18K files) |
-|----------|:---------------------:|:---------------------------:|:-----------------:|
-| `grep` / `ripgrep` | No | No | 100-500ms |
-| IDE search | No | No | 200-1000ms |
-| GitHub search | Partial | No | 500-2000ms |
-| **Magector** | **Yes** | **Yes** | **10-45ms** |
+Generic search tools — `grep`, IDE search, or the keyword matching built into AI assistants — can't bridge this gap. They find literal strings but can't connect *"how does checkout calculate totals?"* to `TotalsCollector.php` when the word "totals" appears in hundreds of unrelated files.
 
-Magector understands that a query about *"payment capture"* should return `Sales/Model/Order/Payment/Operations/CaptureOperation.php`, not just files containing the word "capture".
+Magector solves this with three layers of intelligence:
 
----
+1. **Semantic vector index** — every file is embedded into a 384-dimensional space (ONNX, all-MiniLM-L6-v2) where meaning matters more than keywords. A search for *"payment capture"* returns `CaptureOperation.php` because the embeddings are close, not because the file contains the word "capture".
 
-## Magector vs Built-in AI Search
+2. **Magento technology awareness** — 20+ pattern detectors identify plugins, observers, controllers, blocks, cron jobs, GraphQL resolvers, DI preferences, layout XML, and more. Every search result is enriched with what kind of Magento component it is, so the AI client understands the code's role in the system.
 
-Claude Code and Cursor both have built-in code search -- but they rely on keyword matching (`grep`/`ripgrep`) and file-tree heuristics. On a Magento 2 / Adobe Commerce codebase with 18,000+ files, that approach breaks down fast.
+3. **Adaptive learning (SONA)** — Magector tracks which results you actually use and adjusts future rankings with MicroLoRA feedback, getting smarter over time without any API calls.
 
-| Capability | Claude Code / Cursor (built-in) | Magector |
-|---|---|---|
-| **Search method** | Keyword grep / ripgrep | Semantic vector search (ONNX embeddings) |
-| **Understands intent** | No -- literal string matching only | Yes -- "payment capture" finds `CaptureOperation.php` |
-| **Magento pattern awareness** | None -- treats all PHP the same | Detects controllers, plugins, observers, blocks, resolvers, cron, and 20+ patterns |
-| **Query speed (36K vectors)** | 200-1000ms per grep pass; multiple rounds needed | 10-45ms single pass |
-| **Context window cost** | Reads many wrong files, burns tokens | Returns structured JSON with ranked results, methods, and snippets |
-| **Works offline** | Yes | Yes -- local ONNX model, no API calls |
-| **Setup** | Built-in | `npx magector init` (one command) |
+The result: your AI assistant calls one MCP tool and gets ranked, pattern-enriched results in 10-45ms — instead of burning tokens grepping through dozens of wrong files. High relevance accuracy means the AI reads fewer, more targeted files, which optimizes context window usage, reduces API costs, and accelerates development cycles.
 
-### What this means in practice
-
-Without Magector, asking Claude Code or Cursor *"how are checkout totals calculated?"* triggers multiple grep searches, reads dozens of files, and still may miss the right ones. With Magector, the AI calls `magento_search("checkout totals calculation")` and gets the exact files ranked by relevance in one step -- saving tokens and time.
-
-**Magector doesn't replace your AI tool -- it gives it a better search engine.**
+| Approach | Semantic matches | Magento-aware | Speed (18K files) |
+|----------|:---------------------:|:---------------------------:|:-----------------:|
+| `grep` / `ripgrep` | No | No | 100-500ms |
+| IDE search | No | No | 200-1000ms |
+| GitHub search | Partial | No | 500-2000ms |
+| **Magector** | **Yes** | **Yes** | **10-45ms** |
 
 ---
 
@@ -69,7 +57,8 @@ Without Magector, asking Claude Code or Cursor *"how are checkout totals calcula
 - **Diff analysis** -- risk scoring and change classification for git commits and staged changes
 - **Complexity analysis** -- cyclomatic complexity, function count, and hotspot detection across modules
 - **Fast** -- 10-45ms queries via persistent serve process, batched ONNX embedding with adaptive thread scaling
-- **MCP server** -- 20 tools integrating with Claude Code, Cursor, and any MCP-compatible AI tool
+- **LLM description enrichment** -- generate natural-language descriptions of di.xml files using Claude, stored in SQLite, and prepend them to embedding text so descriptions influence vector search ranking (not just post-retrieval display)
+- **MCP server** -- 21 tools integrating with Claude Code, Cursor, and any MCP-compatible AI tool
 - **Clean architecture** -- Rust core handles all indexing/search, Node.js MCP server delegates to it
 
 ---
@@ -77,22 +66,27 @@ Without Magector, asking Claude Code or Cursor *"how are checkout totals calcula
 ## Architecture
 
 ```mermaid
-flowchart TD
-  subgraph rust ["Rust Core"]
-    A["AST Parser · PHP + JS"]
-    B["Pattern Detection · 20+"]
-    C["ONNX Embedder · 384d"]
-    D["HNSW + Reranking"]
-    A --> B --> C --> D
-  end
+flowchart LR
   subgraph node ["Node.js Layer"]
-    E["MCP Server · 20 tools"]
-    F["Persistent Serve"]
-    G["CLI · init/index/search"]
-    E --> F
+    direction TB
+    G["CLI<br/>init · index · search · describe"]
+    E["MCP Server<br/>21 tools · LRU cache"]
+    F["Persistent Serve Process"]
     G --> F
+    E --> F
+  end
+
+  F -->|"stdin/stdout JSON"| rust
+
+  subgraph rust ["Rust Core"]
+    direction TB
+    A["AST Parser<br/>PHP · JS · XML"]
+    B["Pattern Detection<br/>20+ Magento patterns"]
+    B2["Description Enrichment<br/>LLM-powered di.xml summaries"]
+    C["ONNX Embedder<br/>all-MiniLM-L6-v2 · 384d"]
+    D["HNSW Vector Search<br/>hybrid reranking · SONA"]
+    A --> B --> B2 --> C --> D
   end
-  node -->|stdin/stdout JSON| rust
 
   style rust fill:#f4a460,color:#000
   style node fill:#68b684,color:#000
@@ -101,26 +95,28 @@ flowchart TD
 ### Indexing Pipeline
 
 ```mermaid
-flowchart TD
-  A[Source File] --> B[AST Parser]
-  B --> C[Pattern Detection]
-  C --> D[Text Enrichment]
-  D --> E[ONNX Embedding]
-  E --> F[(HNSW Index)]
-  A --> G[Metadata]
-  G --> F
+flowchart LR
+  A["Source File"] --> B["AST Parser"]
+  B --> C["Pattern Detection"]
+  C --> D["Text Enrichment"]
+  D --> D2{"Descriptions DB?"}
+  D2 -->|Yes| D3["Prepend LLM Description"]
+  D2 -->|No| E["ONNX Embedding"]
+  D3 --> E
+  E --> F[("HNSW Index")]
+  A --> G["Metadata"] --> F
 ```
 
 ### Search Pipeline
 
 ```mermaid
-flowchart TD
-  Q[Query] --> E1[Synonym Enrichment]
-  E1 --> E2[ONNX Embedding]
-  E2 --> H[HNSW Search]
-  H --> R[Hybrid Reranking]
-  R --> SA[SONA Adjustment + MicroLoRA]
-  SA --> J[Structured JSON]
+flowchart LR
+  Q["Query"] --> E1["Synonym Enrichment"]
+  E1 --> E2["ONNX Embedding"]
+  E2 --> H["HNSW Search"]
+  H --> R["Hybrid Reranking"]
+  R --> SA["SONA Adjustment"]
+  SA --> J["Structured JSON"]
 ```
 
 ### Components
@@ -133,6 +129,7 @@ flowchart TD
 | JS parsing | `tree-sitter-javascript` | AMD/ES6 module detection |
 | Pattern detection | Custom Rust | 20+ Magento-specific patterns |
 | CLI | `clap` | Command-line interface (index, search, serve, validate) |
+| Descriptions | `rusqlite` (bundled SQLite) | LLM-generated di.xml descriptions stored in SQLite, prepended to embeddings |
 | SONA | Custom Rust | Feedback learning with MicroLoRA + EWC++ |
 | MCP server | `@modelcontextprotocol/sdk` | AI tool integration with structured JSON output |
 
@@ -154,13 +151,14 @@ npx magector init
 This single command handles the entire setup:
 
 ```mermaid
-flowchart TD
-  A["npx magector init"] --> B[Verify Project]
-  B --> C[Download Model]
-  C --> D[Index Codebase]
-  D --> E[Detect IDE]
-  E --> F[Write Config]
-  F --> G[Update .gitignore]
+flowchart LR
+  A["npx magector init"] --> B["Verify<br/>Project"]
+  B --> C["Download<br/>ONNX Model"]
+  C --> D["Index<br/>Codebase"]
+  D --> E["Detect IDE<br/>Cursor · Claude Code"]
+  E --> E2["API Key<br/>(optional)"]
+  E2 --> F["Write MCP<br/>Config"]
+  F --> G["Update<br/>.gitignore"]
 ```
 
 ### 2. Search
@@ -195,6 +193,7 @@ Commands:
   index       Index a Magento codebase
   search      Search the index semantically
   serve       Start persistent server mode (stdin/stdout JSON protocol)
+  describe    Generate LLM descriptions for di.xml files (requires ANTHROPIC_API_KEY)
   validate    Run validation suite (downloads Magento if needed)
   download    Download Magento 2 Open Source
   stats       Show index statistics
@@ -207,33 +206,50 @@ Commands:
 magector-core index [OPTIONS]
 
 Options:
-  -m, --magento-root <PATH>   Path to Magento root directory
-  -d, --database <PATH>       Index database path [default: ./magector.db]
-  -c, --model-cache <PATH>    Model cache directory [default: ./models]
-  -v, --verbose               Enable verbose output
+  -m, --magento-root <PATH>          Path to Magento root directory
+  -d, --database <PATH>              Index database path [default: ./.magector/index.db]
+  -c, --model-cache <PATH>           Model cache directory [default: ./models]
+      --descriptions-db <PATH>       Path to descriptions SQLite DB (descriptions are prepended to embeddings)
+  -v, --verbose                      Enable verbose output
 ```
 
+When `--descriptions-db` is provided (or auto-detected as `sqlite.db` next to the index), descriptions are prepended to the embedding text as `"Description: {text}\n\n"` before the raw file content. This places semantic terms within the 256-token ONNX window, significantly improving retrieval of di.xml files for natural-language queries.
+
 #### `search`
 
 ```bash
 magector-core search <QUERY> [OPTIONS]
 
 Options:
-  -d, --database <PATH>   Index database path [default: ./magector.db]
+  -d, --database <PATH>   Index database path [default: ./.magector/index.db]
   -l, --limit <N>         Number of results [default: 10]
   -f, --format <FORMAT>   Output format: text, json [default: text]
 ```
 
+#### `describe`
+
+```bash
+magector-core describe [OPTIONS]
+
+Options:
+  -m, --magento-root <PATH>   Path to Magento root directory
+  -o, --output <PATH>         Output SQLite database [default: ./.magector/sqlite.db]
+      --force                 Re-describe all files (ignore cache)
+```
+
+Generates natural-language descriptions of di.xml files using the Anthropic API (Claude Sonnet). Requires `ANTHROPIC_API_KEY` environment variable. Descriptions are stored in a SQLite database and used during indexing to enrich embeddings. Only files with changed content hashes are re-described (incremental by default).
+
 #### `serve`
 
 ```bash
 magector-core serve [OPTIONS]
 
 Options:
-  -d, --database <PATH>       Index database path [default: ./magector.db]
-  -c, --model-cache <PATH>    Model cache directory [default: ./models]
-  -m, --magento-root <PATH>   Magento root (enables file watcher)
-      --watch-interval <SECS> File watcher poll interval [default: 60]
+  -d, --database <PATH>            Index database path [default: ./.magector/index.db]
+  -c, --model-cache <PATH>         Model cache directory [default: ./models]
+  -m, --magento-root <PATH>        Magento root (enables file watcher)
+      --descriptions-db <PATH>     Path to descriptions SQLite DB
+      --watch-interval <SECS>      File watcher poll interval [default: 60]
 ```
 
 Starts a persistent process that reads JSON queries from stdin and writes JSON responses to stdout. Keeps the ONNX model and HNSW index resident in memory for fast repeated queries.
@@ -257,6 +273,16 @@ When `--magento-root` is provided, a background file watcher polls for changed f
 // Response:
 {"ok":true,"data":{"running":true,"tracked_files":18234,"last_scan_changes":3,"interval_secs":60}}
 
+// Descriptions (all LLM descriptions from SQLite DB):
+{"command":"descriptions"}
+// Response:
+{"ok":true,"data":{"app/code/Magento/Catalog/etc/di.xml":{"hash":"...","description":"...","model":"claude-sonnet-4-5-20250929","timestamp":1769875137},...}}
+
+// Describe (generate descriptions + auto-reindex affected files):
+{"command":"describe"}
+// Response:
+{"ok":true,"data":{"files_found":371,"described":5,"skipped":366,"errors":0,"described_paths":["app/code/..."]}}
+
 // SONA feedback:
 {"command":"feedback","signals":[{"type":"refinement_to_plugin","query":"checkout totals","timestamp":1700000000000}]}
 // Response:
@@ -275,26 +301,30 @@ When `--magento-root` is provided, a background file watcher polls for changed f
 npx magector init [path]        # Full setup: index + IDE config
 npx magector index [path]       # Index (or re-index) Magento codebase
 npx magector search <query>     # Search indexed code
+npx magector describe [path]    # Generate LLM descriptions for di.xml files
 npx magector stats              # Show indexer statistics
 npx magector setup [path]       # IDE setup only (no indexing)
 npx magector mcp                # Start MCP server
 npx magector help               # Show help
 ```
 
+The `describe` command and `magento_describe` MCP tool require an Anthropic API key. During `npx magector init`, you are prompted to paste your key (optional). If provided, it is stored in the MCP config file as the `ANTHROPIC_API_KEY` environment variable so the MCP server can use it automatically. You can also set it manually later by adding `"ANTHROPIC_API_KEY": "sk-..."` to the `env` section in `.mcp.json` or `~/.cursor/mcp.json`.
+
 ### Environment Variables
 
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `MAGENTO_ROOT` | Path to Magento installation | Current directory |
-| `MAGECTOR_DB` | Path to index database | `./magector.db` |
+| `MAGECTOR_DB` | Path to index database | `./.magector/index.db` |
 | `MAGECTOR_BIN` | Path to magector-core binary | Auto-detected |
 | `MAGECTOR_MODELS` | Path to ONNX model directory | `~/.magector/models/` |
+| `ANTHROPIC_API_KEY` | API key for description generation (`describe` command) | — |
 
 ---
 
 ## MCP Server Tools
 
-The MCP server exposes 20 tools for AI-assisted Magento 2 and Adobe Commerce development. All search tools return **structured JSON** with file paths, class names, methods, role badges, and content snippets -- enabling AI clients to parse results programmatically and minimize file-read round-trips.
+The MCP server exposes 21 tools for AI-assisted Magento 2 and Adobe Commerce development. All search tools return **structured JSON** with file paths, class names, methods, role badges, and content snippets -- enabling AI clients to parse results programmatically and minimize file-read round-trips.
 
 ### Output Format
 
@@ -371,6 +401,7 @@ Auto-detects entry type from pattern (`/V1/...` → API, `snake_case` → event,
 |------|-------------|
 | `magento_module_structure` | Show complete module structure -- controllers, models, blocks, plugins, observers, configs |
 | `magento_index` | Trigger re-indexing of the codebase |
+| `magento_describe` | Generate LLM descriptions for di.xml files (requires `ANTHROPIC_API_KEY`), stored in SQLite, auto-reindexes affected files |
 | `magento_stats` | View index statistics |
 
 ### Tool Cross-References
@@ -378,7 +409,7 @@ Auto-detects entry type from pattern (`/V1/...` → API, `snake_case` → event,
 Each tool description includes "See also" hints to help AI clients chain tools effectively:
 
 ```mermaid
-graph TD
+graph LR
   cls["find_class"] --> plg["find_plugin"]
   cls --> prf["find_preference"]
   cls --> mtd["find_method"]
@@ -436,6 +467,7 @@ magento_find_block("cart totals")
 magento_find_template("minicart")
 magento_analyze_diff({ commitHash: "abc123" })
 magento_complexity({ module: "Magento_Catalog", threshold: 10 })
+magento_describe()
 magento_trace_flow({ entryPoint: "checkout/cart/add", depth: "deep" })
 magento_trace_flow({ entryPoint: "/V1/products" })
 magento_trace_flow({ entryPoint: "placeOrder", entryType: "graphql" })
@@ -492,7 +524,7 @@ pie title Test Pass Rate (101 queries)
 
 ### Integration Tests
 
-64 integration tests covering MCP protocol compliance, tool schemas, tool calls, analysis tools, and stdout JSON integrity.
+66 integration tests covering MCP protocol compliance, tool schemas, tool calls (including `magento_describe`), analysis tools, and stdout JSON integrity.
 
 ### Running Tests
 
@@ -501,7 +533,7 @@ pie title Test Pass Rate (101 queries)
 npm run test:accuracy
 npm run test:accuracy:verbose
 
-# Integration tests (64 tests)
+# Integration tests (66 tests)
 npm test
 
 # SONA/MicroLoRA benefit evaluation (180 queries, baseline vs post-training)
@@ -539,6 +571,7 @@ magector/
 │   ├── mcp-accuracy.test.js      # E2E accuracy tests (101 queries)
 │   ├── mcp-sona.test.js          # SONA feedback integration tests (8 tests)
 │   ├── mcp-sona-eval.test.js     # SONA/MicroLoRA benefit evaluation (180 queries)
+│   ├── describe-benefit-eval.test.js  # Description enrichment benefit evaluation
 │   └── results/                  # Test result artifacts
 │       ├── accuracy-report.json
 │       └── sona-eval-report.json
@@ -558,6 +591,7 @@ magector/
 │   │   ├── watcher.rs             # File watcher for incremental re-indexing
 │   │   ├── ast.rs                 # Tree-sitter AST (PHP + JS)
 │   │   ├── magento.rs             # Magento pattern detection (Rust)
+│   │   ├── describe.rs            # LLM description generation + SQLite storage
 │   │   ├── sona.rs                # SONA feedback learning + MicroLoRA + EWC++
 │   │   └── validation.rs          # 557 test cases, validation framework
 │   └── models/                   # ONNX model files (auto-downloaded)
@@ -587,8 +621,9 @@ Magector scans every `.php`, `.js`, `.xml`, `.phtml`, and `.graphqls` file in a
 1. **AST parsing** -- Tree-sitter extracts class names, namespaces, methods, inheritance, and interface implementations from PHP and JavaScript files
 2. **Pattern detection** -- Identifies Magento-specific patterns: controllers, models, repositories, plugins, observers, blocks, GraphQL resolvers, admin grids, cron jobs, and more
 3. **Search text enrichment** -- Combines AST metadata with Magento pattern keywords to create semantically rich text representations
-4. **Embedding** -- ONNX Runtime generates 384-dimensional vectors using all-MiniLM-L6-v2
-5. **Indexing** -- Vectors are stored in an HNSW index for sub-millisecond approximate nearest neighbor search
+4. **Description enrichment** -- If a descriptions SQLite DB is present, LLM-generated natural-language descriptions are prepended to the embedding text as `"Description: {text}\n\n"`, placing semantic DI concepts (preferences, plugins, virtual types, subsystem names) within the 256-token ONNX window
+5. **Embedding** -- ONNX Runtime generates 384-dimensional vectors using all-MiniLM-L6-v2
+6. **Indexing** -- Vectors are stored in an HNSW index for sub-millisecond approximate nearest neighbor search
 
 ### 2. Searching
 
@@ -604,20 +639,16 @@ Magector scans every `.php`, `.js`, `.xml`, `.phtml`, and `.graphqls` file in a
 The MCP server spawns a persistent Rust process (`magector-core serve`) that keeps the ONNX model and HNSW index loaded in memory. Queries are sent as JSON over stdin and responses returned via stdout -- eliminating the ~2.6s cold-start overhead of loading the model per query. Falls back to single-shot `execFileSync` if the serve process is unavailable.
 
 ```mermaid
-flowchart TD
+flowchart LR
   subgraph startup ["Startup (once)"]
-    S1[Load Model] --> S2[Load Index]
-    S2 --> S3[Ready Signal]
+    S1["Load Model"] --> S2["Load Index"] --> S3["Ready Signal"]
   end
+  startup --> query
   subgraph query ["Per Query (10-45ms)"]
-    Q1[stdin JSON] --> Q2[Embed]
-    Q2 --> Q3[HNSW Search]
-    Q3 --> Q4[Rerank]
-    Q4 --> Q5[stdout JSON]
+    Q1["stdin JSON"] --> Q2["Embed"] --> Q3["HNSW Search"] --> Q4["Rerank"] --> Q5["stdout JSON"]
   end
-  startup --> query
   subgraph fallback ["Fallback"]
-    F1[execFileSync ~2.6s]
+    F1["execFileSync ~2.6s"]
   end
 
   style startup fill:#e8f4e8,color:#000
@@ -632,17 +663,12 @@ When the serve process is started with `--magento-root`, a background thread pol
 Since `hnsw_rs` does not support point deletion, Magector uses a **tombstone** strategy: old vectors for modified/deleted files are marked as tombstoned and filtered out of search results. New vectors are appended. When tombstoned entries exceed 20% of total vectors, the HNSW graph is automatically rebuilt (compacted) to reclaim memory and restore search performance.
 
 ```mermaid
-flowchart TD
-  W1[Sleep 60s] --> W2[Scan Filesystem]
-  W2 --> W3{Changes?}
+flowchart LR
+  W1["Sleep 60s"] --> W2["Scan Filesystem"] --> W3{"Changes?"}
   W3 -->|No| W1
-  W3 -->|Yes| W4[Tombstone Old Vectors]
-  W4 --> W5[Parse + Embed New Files]
-  W5 --> W6[Append to HNSW]
-  W6 --> W7{Tombstone > 20%?}
-  W7 -->|Yes| W8[Compact / Rebuild HNSW]
-  W7 -->|No| W9[Save to Disk]
-  W8 --> W9
+  W3 -->|Yes| W4["Tombstone Old Vectors"] --> W5["Parse + Embed New Files"] --> W6["Append to HNSW"] --> W7{"Tombstone > 20%?"}
+  W7 -->|Yes| W8["Compact / Rebuild HNSW"] --> W9["Save to Disk"]
+  W7 -->|No| W9
   W9 --> W1
 
   style W4 fill:#f4e8e8,color:#000
@@ -694,7 +720,7 @@ The MCP server tracks sequences of tool calls and sends feedback signals to the
 - Learning rate decays with repeated observations (diminishing returns)
 - Learned weights are keyed by normalized, order-independent query term hashes
 - Always active -- no feature flags or build-time opt-in required
-- Persisted via bincode to `<db_path>.sona`
+- Persisted via bincode to `<db_path>.sona` (e.g., `.magector/index.db.sona`)
 
 **SONA v2: MicroLoRA + EWC++**
 
@@ -714,6 +740,34 @@ SONA v2 adds embedding-level adaptation via a MicroLoRA adapter and Elastic Weig
 cd rust-core && cargo build --release
 ```
 
+### 7. LLM Description Enrichment
+
+Magector can generate natural-language descriptions of di.xml files using the Anthropic API and embed them directly into the vector index. This significantly improves search ranking for semantic queries about dependency injection.
+
+**Workflow:**
+
+```bash
+# 1. Generate descriptions (one-time, incremental — only re-describes changed files)
+ANTHROPIC_API_KEY=sk-... npx magector describe /path/to/magento
+
+# 2. Re-index with descriptions embedded into vectors
+npx magector index /path/to/magento
+```
+
+Or via the MCP tool: `magento_describe()` generates descriptions and auto-reindexes affected files in one step.
+
+**How it works:** Each di.xml file is sent to Claude Sonnet with a prompt optimized for semantic search retrieval. The resulting description (~70 words) is stored in a SQLite database (`.magector/sqlite.db`). During indexing, descriptions are prepended to the embedding text as `"Description: {text}\n\n"` before the raw file content, placing semantic terms (preferences, plugins, virtual types, subsystem names) within the ONNX model's 256-token window.
+
+**Measured impact** (A/B experiment, 25 queries, Magento 2.4.7, 17,891 vectors, 371 described files):
+
+| Metric | Without Descriptions | With Descriptions | Delta |
+|--------|---------------------|-------------------|-------|
+| Precision@K | 1.6% | 20.3% | **+18.7%** |
+| MRR | 0.031 | 0.330 | **+0.30** |
+| NDCG@10 | 0.037 | 0.369 | **+0.33** |
+| di.xml results/query | 0.2 | 3.0 | **+2.8** |
+| Query win rate | — | — | **76%** |
+
 ---
 
 ## Magento Patterns Detected
@@ -830,7 +884,7 @@ cargo run --release -- validate
 ### Testing
 
 ```bash
-# Integration tests (64 tests, requires indexed codebase)
+# Integration tests (66 tests, requires indexed codebase)
 npm test
 
 # E2E accuracy tests (101 queries)
@@ -840,7 +894,7 @@ npm run test:accuracy:verbose
 # Run without index (unit + schema tests only)
 npm run test:no-index
 
-# Rust unit tests (33 tests including SONA)
+# Rust unit tests (37 tests including SONA + descriptions)
 cd rust-core && cargo test
 
 # SONA integration tests (8 tests)
@@ -968,12 +1022,13 @@ gantt
     SONA feedback       :done, 2025-04, 30d
     Incremental index   :done, 2025-04, 30d
     SONA v2 MicroLoRA   :done, 2025-05, 15d
-    Method chunking     :active, 2025-06, 30d
-    Intent detection    :2025-07, 30d
-    Type filtering      :2025-08, 30d
+    LLM descriptions    :done, 2025-06, 30d
+    Method chunking     :active, 2025-07, 30d
+    Intent detection    :2025-08, 30d
+    Type filtering      :2025-09, 30d
   section Future
-    VSCode extension    :2025-09, 60d
-    Web UI              :2025-11, 60d
+    VSCode extension    :2025-10, 60d
+    Web UI              :2025-12, 60d
 ```
 
 - [x] Hybrid search (semantic + keyword re-ranking)
@@ -984,6 +1039,7 @@ gantt
 - [x] Adobe Commerce support (B2B, Staging, and all Commerce-specific modules)
 - [x] SONA feedback learning (search rankings adapt to MCP tool call patterns)
 - [x] SONA v2 with MicroLoRA + EWC++ (embedding-level adaptation, prevents catastrophic forgetting)
+- [x] LLM description enrichment (generate di.xml descriptions via Claude, store in SQLite, embed into vectors for improved search ranking)
 - [ ] Method-level chunking (per-method vectors for direct method search)
 - [ ] Query intent classification (auto-detect "give me XML" vs "give me PHP")
 - [ ] Filtered search by file type at the vector level

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magector",
-  "version": "1.4.3",
+  "version": "1.5.1",
   "description": "Semantic code search for Magento 2 — index, search, MCP server",
   "type": "module",
   "main": "src/mcp-server.js",
@@ -25,7 +25,9 @@
     "test:accuracy": "node tests/mcp-accuracy.test.js",
     "test:accuracy:verbose": "node tests/mcp-accuracy.test.js --verbose",
     "test:sona-eval": "node tests/mcp-sona-eval.test.js",
-    "test:sona-eval:verbose": "node tests/mcp-sona-eval.test.js --verbose"
+    "test:sona-eval:verbose": "node tests/mcp-sona-eval.test.js --verbose",
+    "test:describe-eval": "node tests/describe-benefit-eval.test.js",
+    "test:describe-eval:verbose": "node tests/describe-benefit-eval.test.js --verbose"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
@@ -35,10 +37,10 @@
     "ruvector": "^0.1.96"
   },
   "optionalDependencies": {
-    "@magector/cli-darwin-arm64": "1.4.3",
-    "@magector/cli-linux-x64": "1.4.3",
-    "@magector/cli-linux-arm64": "1.4.3",
-    "@magector/cli-win32-x64": "1.4.3"
+    "@magector/cli-darwin-arm64": "1.5.1",
+    "@magector/cli-linux-x64": "1.5.1",
+    "@magector/cli-linux-arm64": "1.5.1",
+    "@magector/cli-win32-x64": "1.5.1"
   },
   "keywords": [
     "magento",