feat: add semantic search mode (--mode semantic)

Natural-language code search via HNSW vector similarity:
- Embeds query via Ollama at search time using ~/.config/magellan/config.toml
- Loads persisted HNSW index (symbols) from Magellan database
- Resolves vector hits back to graph_entities with distance + similarity score
- Supports --path filtering and all output formats
- Graceful error when no HNSW index exists
- llmgrep only searches; Magellan owns embedding generation

New files:
- src/query/semantic.rs — core implementation + 8 unit tests

Updated:
- src/commands/search.rs — Semantic dispatch branch
- src/display.rs — output_semantic() formatting
- src/output.rs — SemanticMatch + SemanticSearchResponse types
- src/query/mod.rs — module export
- src/cli.rs — SearchMode::Semantic variant + examples
- Cargo.toml — added ureq, toml deps; bumped to 3.8.0
- MANUAL.md, README.md, CHANGELOG.md — documentation

Author: oldnordic

CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **`semantic` search mode** (`--mode semantic`) — Natural-language code search via HNSW vector similarity:
+  - Embeds the query via Ollama at search time using `~/.config/magellan/config.toml`
+  - Loads the persisted HNSW index (`symbols`) from the Magellan database
+  - Resolves vector hits back to `graph_entities` with file paths, kinds, and FQNs
+  - Returns cosine distance + 0-100 similarity score
+  - Supports `--path` filtering and all output formats (`human`, `json`, `pretty`)
+  - Graceful error when no HNSW index exists: suggests `magellan embed --db <db>`
+  - llmgrep only **searches** embeddings; Magellan owns embedding generation
+  ```bash
+  llmgrep search --db code.db --query "parse command line arguments" --mode semantic
+  llmgrep search --db code.db --query "error handling" --mode semantic --output json
+  ```
+
 ## [3.7.0] - 2026-05-29
 
 ### Added

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "llmgrep"
-version = "3.7.0"
+version = "3.8.0"
 edition = "2021"
 description = "Smart grep over Magellan code maps with schema-aligned JSON output"
 license = "GPL-3.0-only"
@@ -32,6 +32,8 @@ signal-hook = "0.3"
 sqlitegraph = "3.2.5"
 tempfile = "3.10"
 thiserror = "1.0"
+toml = "0.8"
+ureq = "3"
 
 [dev-dependencies]
 rusqlite = "0.31"

Cargo.toml

@@ -1,6 +1,6 @@
 # llmgrep Manual
 
-**v3.6.0** (shipped 2026-05-28)
+**v3.8.0** (shipped 2026-06-07)
 
 llmgrep is a read-only query tool for Magellan's code map. Part of the sqlitegraph toolset alongside Magellan (indexing), Mirage (CFG analysis), and Splice (precision editing).
 
@@ -35,18 +35,49 @@ llmgrep evolve --db <FILE> [OPTIONS]
 | `references` | Search references to symbols |
 | `calls` | Search function calls |
 | `implements` | Search type-trait implementations |
+| `semantic` | Natural-language semantic search via vector similarity (requires embeddings) |
 | `docs` | Search source documents (wiki, specs, messages) |
 | `facts` | Search candidate knowledge triples |
 | `auto` | Run symbols, references, and calls modes combined |
 
+### Semantic search (`--mode semantic`)
+
+Natural-language code search using HNSW vector similarity. Finds symbols by meaning rather than exact name match.
+
+**Prerequisites:**
+- Embeddings must be generated by Magellan: `magellan embed --db <db>`
+- Ollama must be running with the same embedding model configured in `~/.config/magellan/config.toml`
+
+**How it works:**
+1. llmgrep reads `~/.config/magellan/config.toml` to discover the Ollama endpoint and model
+2. The query is embedded via Ollama (query embedding happens at search time)
+3. The persisted HNSW index is loaded from the database
+4. Returns the nearest symbol vectors sorted by cosine similarity
+
+**Important:** llmgrep only **searches** existing embeddings — it does not create them. Magellan owns embedding generation and freshness.
+
+**Examples:**
+```bash
+# Find code related to command-line argument parsing
+llmgrep search --db code.db --query "parse command line arguments" --mode semantic
+
+# Semantic search with path filter
+llmgrep search --db code.db --query "database connection pooling" --mode semantic --path src/db
+
+# JSON output for programmatic use
+llmgrep search --db code.db --query "error handling" --mode semantic --output json
+```
+
+**Graceful degradation:** If the database has no HNSW index, llmgrep returns a clear error suggesting `magellan embed --db <db>`. All other search modes work normally without embeddings.
+
 ### Options
 
 **Required:**
 - `--db <FILE>` — Path to Magellan SQLite database
 - `--query <STRING>` — Search query string
 
 **Search mode:**
-- `--mode <MODE>` — Search mode: `symbols` (default), `references`, `calls`, `implements`, `docs`, `facts`, `auto`
+- `--mode <MODE>` — Search mode: `symbols` (default), `references`, `calls`, `implements`, `semantic`, `docs`, `facts`, `auto`
 
 **Filters:**
 - `--path <PATH>` — Filter by file path prefix