### First-Time Setup Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

Steps for initializing Semantiq for the first time in a project.

```bash
# Clone or cd to project
cd my-project

# Initialize Semantiq
semantiq init

# Restart Claude Code to load config
# .mcp.json is now configured
# .semantiq.db is indexed
# Tools are available
```

--------------------------------

### serve Command MCP Mode Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

Example of starting the Semantiq server in MCP Mode.

```bash
semantiq serve --project .
```

--------------------------------

### Server Startup Examples

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/http-api.md

Demonstrates how to start the Semantiq HTTP API server with different configurations, including port, CORS origin, and custom project/database paths.

```bash
# Start HTTP API on port 3000
semantiq serve --http-port 3000

# With CORS for web clients
semantiq serve --http-port 3000 --cors-origin "https://example.com"

# Custom project path
semantiq serve --http-port 3000 --project /my/project --database /data/index.db
```

--------------------------------

### init Command Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

Examples of initializing Semantiq for a project.

```bash
# Initialize current project
semantiq init

# Initialize specific project
semantiq init /path/to/project
```

--------------------------------

### serve Command HTTP API Mode Examples

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

Examples of starting the Semantiq server in HTTP API Mode.

```bash
semantiq serve --http-port 3000
semantiq serve --http-port 3000 --cors-origin "https://example.com"
```

--------------------------------

### Production HTTP API Example - Start Server

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

Command to start the Semantiq API server with specified ports and CORS origin.

```bash
# Start API server
semantiq serve --http-port 3000 --cors-origin "https://api.example.com"
```

--------------------------------

### SemantiqServer Constructor Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/mcp-server.md

Example of creating a new Semantiq MCP server instance and starting the auto-indexer.

```rust
let server = SemantiqServer::new(
    Path::new("./.semantiq.db"),
    "."
)?;
server.start_auto_indexer(); // Begin background indexing
```

--------------------------------

### semantiq_explain Tool Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/mcp-server.md

Example of using the semantiq_explain tool to get information about a symbol.

```shell
Query: "authenticate"
Returns: # Symbol: authenticate

Found 3 definition(s), 47 usage(s)

## Definition 1 (function)
📄 src/auth/handlers.rs:120-180

```
pub async fn authenticate(req: &Request) -> Result<User>
```

**Documentation:**
Authenticates a request using JWT bearer token.
Returns the authenticated user or an error.

## Related Symbols
- decode_token
- validate_token
- AuthError
```

--------------------------------

### Serve Command Examples

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

Examples of how to run the `semantiq serve` command with different options.

```bash
# MCP stdio mode
semantiq serve --project /my/project

# HTTP API mode
semantiq serve --http-port 3000

# HTTP with CORS
semantiq serve --http-port 3000 --cors-origin "https://ide.example.com"

# Custom database location
semantiq serve --database /data/project.db
```

--------------------------------

### Development Configuration Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Example configuration for running Semantiq in a development environment on a local machine.

```bash
# Development terminal
export RUST_LOG=debug
export SEMANTIQ_ONNX_THREADS=1
semantiq serve --project .
```

--------------------------------

### Index Command Examples

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

Examples of how to use the `semantiq index` command.

```bash
# Index current directory
semantiq index

# Index specific path
semantiq index /path/to/project

# Force full reindex
semantiq index --force

# Custom database
semantiq index --database /data/project.db
```

--------------------------------

### POST /explain Request Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/http-api.md

Example of a POST request to the /explain endpoint to get symbol explanation.

```http
POST /explain HTTP/1.1
Content-Type: application/json

{
  "symbol": "authenticate"
}
```

--------------------------------

### POST /search Examples

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/http-api.md

Command-line examples using curl for basic and filtered searches via the /search endpoint, and a Python client example.

```bash
# Basic search
curl -X POST http://localhost:3000/search \
  -H "Content-Type: application/json" \
  -d '{"query":"authenticate"}'

# With filters
curl -X POST http://localhost:3000/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "handle request",
    "limit": 30,
    "file_type": "rs,ts",
    "symbol_kind": "function,method"
  }'
```

```python
import requests
resp = requests.post(
    'http://localhost:3000/search',
    json={
        'query': 'authenticate user',
        'limit': 20,
        'min_score': 0.5
    }
)
results = resp.json()
for r in results['results']:
    print(f"{r['file_path']}:{r['start_line']} - {r['score']:.2f}")
```

--------------------------------

### Search Command Examples

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

Examples of how to use the `semantiq search` command.

```bash
# Basic search
semantiq search "authentication handler"

# With limit
semantiq search "db connection" --limit 20

# With score threshold
semantiq search "error handling" --min-score 0.5

# Filter by file type
semantiq search "api" --file-type rs,ts

# Filter by symbol kind
semantiq search "handler" --symbol-kind function,method
```

--------------------------------

### Explain Symbol Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/retrieval-engine.md

Demonstrates how to get detailed information about a symbol, including its definitions, usage count, and related symbols.

```rust
let explain = engine.explain_symbol("authenticate")?;
if explain.found {
    for def in &explain.definitions {
        println!("{}: {} at {}:{}", def.kind, explain.name, 
                 def.file_path, def.start_line);
        if let Some(doc) = &def.doc_comment {
            println!("  {}", doc);
        }
    }
    println!("Used {} times", explain.usage_count);
}
```

--------------------------------

### Logging Configuration Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Examples demonstrating how to configure JSON logs for production and human-readable logs for development.

```bash
# JSON logs for production
semantiq --json serve 2> logs/semantiq.log

# Human-readable for development
semantiq serve
```

--------------------------------

### Serve Command Example: Default

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Example of running the 'semantiq serve' command with default settings, using MCP stdio and the current directory as the project root.

```bash
semantiq serve
```

--------------------------------

### Serve Command Example: Custom Locations

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Example of running 'semantiq serve' with custom paths for the project directory and the database file.

```bash
semantiq serve --project /my/project --database /tmp/index.db
```

--------------------------------

### GET /stats Usage Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/http-api.md

Command-line example using curl to retrieve index statistics from the HTTP API.

```bash
curl http://localhost:3000/stats
```

--------------------------------

### Installation

Source: https://github.com/so-keyldzn/semantiq/blob/main/README.md

Install Semantiq using npm or from source via Cargo.

```bash
# npm (recommended)
npm install -g semantiq-mcp

# Cargo (from source)
cargo install --git https://github.com/so-keyldzn/semantiq.git
```

--------------------------------

### Index Command Example: Custom Database

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Example of running 'semantiq index' with a custom path for the database file.

```bash
semantiq index --database /data/project.db
```

--------------------------------

### SearchOptions::new() Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/retrieval-engine.md

Example of creating SearchOptions with default values.

```rust
SearchOptions::new().with_min_score(0.5)
```

--------------------------------

### CI/CD Configuration Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Example configuration for using Semantiq in a Continuous Integration/Continuous Deployment pipeline for testing purposes.

```bash
# Build index for snapshot testing
semantiq index --force

# Report statistics
semantiq stats

# Query from CI
semantiq search "critical" --min-score 0.8
```

--------------------------------

### Get Dependencies Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/retrieval-engine.md

Shows how to retrieve the dependencies (imports) of a given file and print their target path, import name, and kind.

```rust
let deps = engine.get_dependencies("src/main.rs")?;
for dep in deps {
    println!("imports {} from {} [{}]",
             dep.import_name.unwrap_or("_"),
             dep.target_path, dep.kind);
}
```

--------------------------------

### Index Command Example: Current Directory

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Example of running the 'semantiq index' command to index the current directory with the default database.

```bash
semantiq index
```

--------------------------------

### IndexStore::open constructor example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/index-store.md

Example of opening or creating a SQLite database file for the IndexStore.

```rust
let store = IndexStore::open(Path::new("./.semantiq.db"))?;
```

--------------------------------

### Language::from_path Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/parser.md

Example demonstrating how to determine a language from a file path.

```rust
let lang = Language::from_path(Path::new("src/main.rs")); // Some(Language::Rust)
```

--------------------------------

### Index Statistics Response

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

Example response for the GET /stats endpoint.

```json
{
  "files": 42,
  "symbols": 312,
  "chunks": 128,
  "dependencies": 85
}
```

--------------------------------

### First-Time Setup

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/README.md

Command to initialize Semantiq in a project directory.

```bash
cd /my/project
semantiq init          # Creates .mcp.json, indexes
# Restart IDE → tools available
```

--------------------------------

### Install Semantiq MCP Globally

Source: https://github.com/so-keyldzn/semantiq/blob/main/npm/README.md

Install the Semantiq MCP command-line tool globally using npm.

```bash
npm install -g semantiq-mcp
```

--------------------------------

### Language::from_extension Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/parser.md

Example demonstrating how to determine a language from its file extension.

```rust
let lang = Language::from_extension("rs");  // Some(Language::Rust)
let lang = Language::from_extension("py");  // Some(Language::Python)
let lang = Language::from_extension("xyz"); // None
```

--------------------------------

### Get Dependents Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/retrieval-engine.md

Illustrates how to find files that import a specific file and print their target paths.

```rust
let dependents = engine.get_dependents("src/auth/mod.rs")?;
for file in dependents {
    println!("{} imports this", file.target_path);
}
```

--------------------------------

### Multiple Projects Configuration Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Example configuration for running multiple Semantiq projects on a shared server, each with its own database and HTTP port.

```bash
# Project 1
semantiq serve --project /proj1 --database /data/proj1.db --http-port 3001

# Project 2 (in separate container/process)
semantiq serve --project /proj2 --database /data/proj2.db --http-port 3002
```

--------------------------------

### Testing Search Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

Examples of using the search command with and without filters.

```bash
# Quick CLI search
semantiq search "handle request"

# With filters
semantiq search "function" --file-type rs --symbol-kind function --limit 30

# Check what was indexed
semantiq stats
```

--------------------------------

### IndexStore::with_conn example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/index-store.md

Example of safely acquiring a database connection and executing a closure.

```rust
store.with_conn(|conn| {
    conn.execute("DELETE FROM symbols WHERE file_id = ?", [file_id])?;
    Ok(())
})?;
```

--------------------------------

### LanguageSupport::new Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/parser.md

Example of creating a new LanguageSupport instance and parsing code.

```rust
let support = LanguageSupport::new()?;
let tree = support.parse(Language::Rust, source)?;
```

--------------------------------

### Production Configuration Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Example configuration for deploying Semantiq in a production environment, likely within a Docker container or systemd service.

```bash
# Dockerfile or systemd
semantiq serve \
  --project /opt/project \
  --database /data/index.db \
  --http-port 8080 \
  --cors-origin "https://api.example.com" \
  --no-update-check
```

--------------------------------

### Serve Command Example: No Update Check

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Example of running 'semantiq serve' with the version update check disabled.

```bash
semantiq serve --no-update-check
```

--------------------------------

### Index Command Output Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

An example of the output produced by the `semantiq index` command.

```bash
Indexing /my/project
Scanning files...
Initial index complete: 100 scanned, 42 indexed, 58 skipped
Index: 100 files, 312 symbols, 128 chunks
```

--------------------------------

### Temporary Database

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Example of serving with a temporary database.

```bash
semantiq serve --database /tmp/index.db
```

--------------------------------

### CLI: Start MCP Server

Source: https://github.com/so-keyldzn/semantiq/blob/main/README.md

Start the Semantiq MCP server with various options for project path, database location, and update checks.

```bash
semantiq serve                           # Use current directory
semantiq serve --project /path/to/project
semantiq serve --database /custom/path.db
semantiq serve --no-update-check         # Disable version notifications
```

--------------------------------

### Search Command Output Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

An example of the output produced by the `semantiq search` command.

```bash
Found 12 results for 'authenticate' (45 ms)

📄 src/auth/handlers.rs
   Lines 10-45 | Score: 0.92
   Symbol: authenticate (function)
   ```
   pub async fn authenticate(req: &Request) -> Result<User>
   ```

📄 src/api/routes.rs
   Lines 120-125 | Score: 0.75
   Symbol: route_authenticate (function)
```

--------------------------------

### Import Struct Example (Python)

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/types.md

Example of how an import is represented in Python.

```rust
// Python: from . import helpers
Import {
    path: ".".to_string(),
    name: Some("helpers".to_string()),
    kind: ImportKind::Local,
    ...
}
```

--------------------------------

### IndexStore::get_stats example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/index-store.md

Example of retrieving index statistics from the store.

```rust
let stats = store.get_stats()?;
println!("Indexed {} files with {} symbols", 
         stats.file_count, stats.symbol_count);
```

--------------------------------

### Import Struct Example (Rust)

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/types.md

Example of how an import is represented in Rust.

```rust
// Rust: use std::io as io_module;
Import {
    path: "std::io".to_string(),
    name: Some("io_module".to_string()),
    kind: ImportKind::Std,
    ...
}
```

--------------------------------

### Successful Indexing Log Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/auto-indexer.md

Example log output indicating successful indexing.

```text
Starting initial index of /path
Initial index complete: X scanned, Y indexed, Z skipped
```

--------------------------------

### Combined Search Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

Example of a combined search query with various filters.

```bash
semantiq search "login" --limit 50 --min-score 0.4 --file-type py,ts
```

--------------------------------

### bootstrap_status() Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/retrieval-engine.md

Example of checking the ML bootstrap status for distance collection.

```rust
if let Some((bootstrapping, progress, count)) = engine.bootstrap_status() {
    println!("Calibration: {} ({}/{})", 
             if bootstrapping { "bootstrapping" } else { "complete" },
             count, 500);
}
```

--------------------------------

### Global Flags Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

Examples of using global flags with the semantiq CLI.

```bash
semantiq --verbose init
semantiq --json serve --project .
```

--------------------------------

### POST /explain Response Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/http-api.md

Example of a successful JSON response from the /explain endpoint.

```json
{
  "name": "authenticate",
  "found": true,
  "definitions": [
    {
      "file_path": "src/auth/handlers.rs",
      "start_line": 10,
      "end_line": 45,
      "kind": "function",
      "signature": "pub async fn authenticate(req: &Request) -> Result<User>",
      "doc_comment": "Authenticates a request using JWT bearer token.\nReturns the authenticated user or an error."
    }
  ],
  "usage_count": 47,
  "related_symbols": [
    "decode_token",
    "validate_token",
    "AuthError"
  ]
}
```

--------------------------------

### SearchOptions::with_file_types() Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/retrieval-engine.md

Example of filtering search results by file types.

```rust
SearchOptions::new()
    .with_file_types(vec!["rs".to_string(), "ts".to_string()])
```

--------------------------------

### Semantiq Index Statistics Output Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/README.md

Example output format for the `semantiq stats` command.

```text
Semantiq Index Statistics
========================
Database: /path/to/.semantiq.db
Files indexed: 26
Symbols: 313
Chunks: 85
Dependencies: 142
```

--------------------------------

### Initial Indexing Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/auto-indexer.md

Demonstrates how to perform an initial index and access the results.

```rust
let indexer = AutoIndexer::new(store, PathBuf::from("."))?;
let result = indexer.initial_index()?;
println!("Indexed {} files ({} skipped)", result.indexed, result.skipped);
```

--------------------------------

### Rust Integration Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/parser.md

This example shows how to initialize the parser, read a Rust source file, parse it, and extract symbols, chunks, and imports.

```rust
use semantiq_parser::{Language, LanguageSupport, SymbolExtractor, 
                       ChunkExtractor, ImportExtractor};

// Initialize
let mut support = LanguageSupport::new()?;
let chunker = ChunkExtractor::new();

// Read a file
let source = std::fs::read_to_string("src/main.rs")?;

// Parse
let tree = support.parse(Language::Rust, &source)?;

// Extract
let symbols = SymbolExtractor::extract(&tree, &source, Language::Rust)?;
let chunks = chunker.extract(&tree, &source, Language::Rust)?;
let imports = ImportExtractor::extract(&tree, &source, Language::Rust)?;

// Use extracted data
for symbol in symbols {
    println!("{} {} at line {}", 
             symbol.kind.as_str(), symbol.name, symbol.start_line);
}
```

--------------------------------

### Shared Database

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Example of serving with a shared database for multiple projects.

```bash
semantiq serve --database /data/shared-index.db
```

--------------------------------

### Check Model Directory

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Example command to check the model directory for pre-downloaded models.

```bash
ls ~/.local/share/semantiq/models/
```

--------------------------------

### Production HTTP API Example - Test Endpoint

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

Examples of testing the Semantiq API endpoints using curl.

```bash
# Test endpoint
curl http://localhost:3000/health
curl -X POST http://localhost:3000/search \
  -H "Content-Type: application/json" \
  -d '{"query":"authenticate","limit":10}'
```

--------------------------------

### semantiq_find_refs Tool Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/mcp-server.md

Example of a query for the semantiq_find_refs tool and its expected return format.

```text
Query: "DatabaseConnection"
Returns: Found 24 references to 'DatabaseConnection' (32 ms)

## Definitions
📍 src/db/connection.rs:45
   pub struct DatabaseConnection { ... }

## Usages (23 found)
📎 src/api/handlers.rs:120
   let conn = DatabaseConnection::new()?;
```

--------------------------------

### IndexStore::open_in_memory example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/index-store.md

Example of opening an in-memory SQLite database for testing purposes.

```rust
#[test]
fn test_search() {
    let store = IndexStore::open_in_memory()?;
    // test code...
}
```

--------------------------------

### RUST_LOG Example: Specific Modules

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Example of setting RUST_LOG to 'info' for general logs and 'debug' specifically for the 'semantiq' module.

```bash
RUST_LOG=info,semantiq=debug semantiq serve
```

--------------------------------

### Query::new() Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/retrieval-engine.md

Example of creating a Query with automatic term expansion for snake_case and camelCase variations.

```rust
let q = Query::new("find_user");
// text: "find_user"
// expanded_terms: ["findUser", "FindUser"]

// Search uses all terms: "find_user" OR "findUser" OR "FindUser"
```

--------------------------------

### LanguageSupport::parse Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/parser.md

Example of parsing a Rust code string into a tree-sitter syntax tree.

```rust
let tree = support.parse(Language::Rust, "fn main() {}")?;
```

--------------------------------

### Custom Indexing Workflow Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/auto-indexer.md

A Rust example demonstrating how to initialize and use the AutoIndexer for indexing and processing file events.

```rust
use semantiq_index::AutoIndexer;
use std::path::PathBuf;
use std::sync::Arc;

// Initialize
let store = Arc::new(IndexStore::open(Path::new(".semantiq.db"))?);
let indexer = AutoIndexer::new(store, PathBuf::from("."))?;

// Perform initial index
let initial = indexer.initial_index()?;
println!("Initial: {} indexed, {} skipped", 
         initial.indexed, initial.skipped);

// Simulate file changes and processing
for _ in 0..5 {
    let result = indexer.process_events()?;
    if result.indexed > 0 || result.deleted > 0 {
        println!("Updated: {} indexed, {} deleted",
                 result.indexed, result.deleted);
    }
    std::thread::sleep(Duration::from_secs(2));
}
```

--------------------------------

### SEMANTIQ_ONNX_THREADS Example: Single-threaded

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Example of setting SEMANTIQ_ONNX_THREADS to 1 for single-threaded ONNX embedding inference.

```bash
SEMANTIQ_ONNX_THREADS=1 semantiq serve
```

--------------------------------

### File Change Log Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/auto-indexer.md

Example log output for detected file changes and re-indexing.

```text
Auto-indexing enabled
File changed: src/main.rs → re-indexed
```

--------------------------------

### IndexStore Example Usage

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/index-store.md

Provides a comprehensive example of opening an IndexStore, retrieving statistics, and performing connection-based operations like inserting and searching symbols.

```rust
use semantiq_index::{IndexStore, SymbolRecord};
use std::path::Path;

// Open/create database
let store = IndexStore::open(Path::new(".semantiq.db"))?;

// Get statistics
let stats = store.get_stats()?;
println!("Index: {} files, {} symbols", 
         stats.file_count, stats.symbol_count);

// Connection-based operations
store.with_conn(|conn| {
    // Insert a symbol
    conn.execute(
        "INSERT INTO symbols (file_id, name, kind, ...) VALUES (?, ?, ?, ...)",
        [file_id, &name, &kind],
    )?;
    
    // Search symbols
    let mut stmt = conn.prepare(
        "SELECT * FROM symbols_fts WHERE symbols_fts MATCH ?"
    )?;
    let results = stmt.query_map([escaped_query], |row| {
        Ok(SymbolRecord {
            id: row.get(0)?,
            // ... map columns
        })
    })?;
    
    for record in results {
        println!("{:?}", record?);
    }
    
    Ok(())
})?;
```

--------------------------------

### POST /deps Request Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/http-api.md

Example of a POST request to the /deps endpoint to analyze file dependencies.

```http
POST /deps HTTP/1.1
Content-Type: application/json

{
  "file_path": "src/main.rs"
}
```

--------------------------------

### semantiq_search Tool Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/mcp-server.md

Example of a query for the semantiq_search tool and its expected return format.

```text
Query: "authentication handler"
Returns: Found 12 results for 'authentication handler' (45 ms)
📄 src/auth/middleware.rs
   Lines 10-45 | Score: 0.92
   Symbol: authenticate (function)
```

--------------------------------

### GET /health Usage Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/http-api.md

Command-line example using curl to check the health of the HTTP API.

```bash
curl http://localhost:3000/health
```

--------------------------------

### RUST_LOG Example: Debug All

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Example of setting the RUST_LOG environment variable to 'debug' to enable detailed debugging across all modules.

```bash
RUST_LOG=debug semantiq serve
```

--------------------------------

### Quick Start Initialization

Source: https://github.com/so-keyldzn/semantiq/blob/main/README.md

Initialize Semantiq for your project, which sets up the MCP server, creates necessary configuration files, and indexes the project.

```bash
cd /path/to/your/project
semantiq init
```

--------------------------------

### HTTP API Usage - Start HTTP Server

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/README.md

Command to start the Semantiq HTTP server for API access.

```bash
semantiq serve --http-port 3000
```

--------------------------------

### Health Check Response

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

Example response for the GET /health endpoint.

```json
{
  "status": "ok",
  "version": "0.8.0"
}
```

--------------------------------

### hash_content Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/index-store.md

Compute content hash for change detection.

```rust
let hash1 = IndexStore::hash_content(source);
let hash2 = IndexStore::hash_content(source);
assert_eq!(hash1, hash2); // Same content = same hash
```

--------------------------------

### GET /health Request and Response

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/http-api.md

Example HTTP request for the /health endpoint and its successful JSON response.

```http
GET /health HTTP/1.1
```

```json
{
  "status": "ok",
  "version": "0.8.0"
}
```

--------------------------------

### Kubernetes Deployment

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/http-api.md

Example Kubernetes Deployment configuration for the semantiq application.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: semantiq
spec:
  replicas: 2
  selector:
    matchLabels:
      app: semantiq
  template:
    metadata:
      labels:
        app: semantiq
    spec:
      containers:
      - name: semantiq
        image: semantiq:latest
        args: ["serve", "--http-port", "3000", "--project", "/project"]
        ports:
        - containerPort: 3000
        livenessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 5
          periodSeconds: 10
        resources:
          requests:
            memory: "256Mi"
            cpu: "500m"
          limits:
            memory: "1Gi"
            cpu: "2000m"
        volumeMounts:
        - name: project
          mountPath: /project
        - name: index
          mountPath: /data
      volumes:
      - name: project
        hostPath:
          path: /my/project
      - name: index
        persistentVolumeClaim:
          claimName: semantiq-index
```

--------------------------------

### Cursor Configuration

Source: https://github.com/so-keyldzn/semantiq/blob/main/README.md

Example JSON configuration for Cursor.

```json
// .cursor/mcp.json
{
  "mcpServers": {
    "semantiq": {
      "command": "semantiq",
      "args": ["serve", "--project", "."]
    }
  }
}
```

--------------------------------

### GET /stats Request and Response

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/http-api.md

Example HTTP request for the /stats endpoint and its successful JSON response containing index statistics.

```http
GET /stats HTTP/1.1
```

```json
{
  "files": 42,
  "symbols": 312,
  "chunks": 128,
  "dependencies": 85
}
```

--------------------------------

### Debugging Example - Verbose Logging

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

Command to enable verbose logging for debugging.

```bash
# Verbose logging
semantiq --verbose serve
```

--------------------------------

### Claude Desktop Configuration (macOS)

Source: https://github.com/so-keyldzn/semantiq/blob/main/README.md

Example JSON configuration for Claude Desktop on macOS.

```json
// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "semantiq": {
      "command": "/usr/local/bin/semantiq",
      "args": ["serve", "--project", "/absolute/path/to/project"]
    }
  }
}
```

--------------------------------

### Configuration Priority Matrix Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Illustrates how configuration values are resolved based on their priority, showing CLI arguments overriding environment variables and defaults.

```bash
# Uses: /custom/db (CLI wins)
semantiq index --database /custom/db

# Uses: /custom/db (CLI missing, check env)
SEMANTIQ_DB_PATH=/custom/db semantiq index

# Uses: ./.semantiq.db (both missing, use default)
semantiq index
```

--------------------------------

### Set Cache Duration

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Example of setting the cache duration for GitHub version checks.

```bash
SEMANTIQ_UPDATE_CACHE_HOURS=1 semantiq serve
```

--------------------------------

### Quick Project Initialization

Source: https://github.com/so-keyldzn/semantiq/blob/main/npm/README.md

Initialize Semantiq MCP for your project to automatically configure settings, generate tool instructions, and index your codebase.

```bash
cd /path/to/your/project
semantiq init
```

--------------------------------

### Error Log Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/auto-indexer.md

Example log output for auto-indexing errors or failures.

```text
Auto-indexing disabled: [reason]
Failed to index src/broken.rs: [error]
```

--------------------------------

### Retrieval Engine Integration Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/retrieval-engine.md

Demonstrates how to set up and use the RetrievalEngine for searching, dependency analysis, and symbol explanation.

```rust
use semantiq_retrieval::{RetrievalEngine, SearchOptions};
use semantiq_index::IndexStore;
use std::path::Path;
use std::sync::Arc;

// Setup
let store = Arc::new(IndexStore::open(Path::new(".semantiq.db"))?);
let engine = RetrievalEngine::new(store, ".");

// Search with options
let results = engine.search(
    "connect to database",
    20,
    Some(SearchOptions::new()
        .with_min_score(0.4)
        .with_file_types(vec!["rs".to_string(), "py".to_string()])
        .with_symbol_kinds(vec!["function".to_string()]))
)?;

// Analyze results
println!("Found {} results in {} ms", 
         results.total_count, results.search_time_ms);

for result in results.results {
    println!("📄 {}:வைக்{}", result.file_path, result.start_line);
    println!("  Score: {:.2}", result.score);
    if let Some(name) = &result.metadata.symbol_name {
        println!("  Symbol: {}", name);
    }
}

// Dependency analysis
let deps = engine.get_dependencies("src/main.rs")?;
let dependents = engine.get_dependents("src/db.rs")?;

// Symbol explanation
let explain = engine.explain_symbol("authenticate")?;
for def in &explain.definitions {
    println!("{}:{}: {}", def.file_path, def.start_line, def.kind);
}

```

--------------------------------

### SearchOptions::with_symbol_kinds() Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/retrieval-engine.md

Example of filtering search results by symbol kinds.

```rust
SearchOptions::new()
    .with_symbol_kinds(vec!["function".to_string(), "method".to_string()])
```

--------------------------------

### Extract Imports Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/parser.md

Example of how to extract imports from source code using the ImportExtractor.

```Rust
let imports = ImportExtractor::extract(&tree, source, Language::Go)?;
for import in imports {
    println!("{} from {} [{}]", import.name.unwrap_or("_"), 
             import.path, import.kind.as_str());
}
```

--------------------------------

### CLI: Initialize Semantiq

Source: https://github.com/so-keyldzn/semantiq/blob/main/README.md

Initialize Semantiq for a project. Can specify a path or use the current directory.

```bash
semantiq init              # Current directory
semantiq init /my/project  # Specific path
```

--------------------------------

### Cursor / VS Code Setup

Source: https://github.com/so-keyldzn/semantiq/blob/main/README.md

Run this command to set up Semantiq configurations specifically for Cursor and VS Code.

```bash
semantiq init-cursor
```

--------------------------------

### Manual creation for Windsurf

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Command to manually create the .windsurf/mcp.json file by copying the .mcp.json content.

```bash
mkdir -p .windsurf
cp .mcp.json .windsurf/mcp.json
```

--------------------------------

### POST /deps Response Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/http-api.md

Example of a successful JSON response from the /deps endpoint.

```json
{
  "imports": [
    {
      "target_path": "std::io",
      "import_name": null,
      "kind": "std"
    },
    {
      "target_path": "src/db/connection.rs",
      "import_name": "db",
      "kind": "local"
    },
    {
      "target_path": "serde",
      "import_name": null,
      "kind": "external"
    }
  ],
  "imported_by": [
    {
      "target_path": "src/api/routes.rs"
    },
    {
      "target_path": "src/worker/tasks.rs"
    }
  ]
}
```

--------------------------------

### POST /find-refs Response Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/http-api.md

Example of a successful JSON response from the /find-refs endpoint.

```json
{
  "query": "DatabaseConnection",
  "results": [
    {
      "kind": "symbol",
      "file_path": "src/db/connection.rs",
      "start_line": 45,
      "end_line": 120,
      "content": "pub struct DatabaseConnection { ... }",
      "score": 1.0,
      "metadata": {
        "symbol_name": "DatabaseConnection",
        "symbol_kind": "struct",
        "match_type": "definition",
        "context": null
      }
    },
    {
      "kind": "reference",
      "file_path": "src/api/handlers.rs",
      "start_line": 20,
      "end_line": 20,
      "content": "let conn: DatabaseConnection = db.connect()?;",
      "score": 0.95,
      "metadata": {
        "symbol_name": "DatabaseConnection",
        "symbol_kind": "struct",
        "match_type": "usage",
        "context": null
      }
    }
  ],
  "total_count": 24,
  "search_time_ms": 32
}
```

--------------------------------

### Incremental Indexing Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

Commands for incremental indexing after file changes or using serve mode.

```bash
# After major file changes
semantiq index

# Or use the always-on serve mode which auto-indexes
semantiq serve --project .
```

--------------------------------

### Retrieval Engine Search Flow Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/index-store.md

Illustrates how the RetrievalEngine utilizes the IndexStore for symbol and semantic searches, and import analysis.

```rust
let store = Arc::new(IndexStore::open(db_path)?);
let engine = RetrievalEngine::new(store, project_root);

let results = engine.search("authenticate", 20, None)?;
```

--------------------------------

### POST /explain cURL Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/http-api.md

cURL command to execute a POST request to the /explain endpoint.

```bash
curl -X POST http://localhost:3000/explain \
  -H "Content-Type: application/json" \
  -d '{"symbol":"authenticate"}'
```

--------------------------------

### POST /explain Response

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/cli-commands.md

Example JSON response body for the /explain API endpoint.

```json
{
  "name": "authenticate",
  "found": true,
  "definitions": [
    {
      "file_path": "src/auth/handlers.rs",
      "start_line": 10,
      "end_line": 45,
      "kind": "function",
      "signature": "pub async fn authenticate(req: &Request) -> Result<User>"
    }
  ],
  "usage_count": 47,
  "related_symbols": ["decode_token", "validate_token"]
}
```

--------------------------------

### AutoIndexer Flow Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/index-store.md

Demonstrates the typical flow of the AutoIndexer using the IndexStore for initial indexing and incremental updates.

```rust
let store = Arc::new(IndexStore::open(db_path)?);
let indexer = AutoIndexer::new(store.clone(), project_root)?;

// Initial indexing
let result = indexer.initial_index()?;
println!("Indexed {} files", result.indexed);

// File watching & incremental updates
loop {
    indexer.process_events()?;
}
```

--------------------------------

### semantiq_deps Tool Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/mcp-server.md

Example of using the semantiq_deps tool to analyze file dependencies.

```shell
Query: "src/db/connection.rs"
Returns: Dependency analysis for 'src/db/connection.rs'

## Imports (5 dependencies)
→ std::sync::Arc
→ sqlx::Pool
→ crate::config (as Config)
→ crate::error

## Imported by (8 files)
← src/api/handlers.rs
← src/worker/queue.rs
```

--------------------------------

### Resolve Local Import Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/parser.md

Example demonstrating the usage of resolve_local_import to resolve a relative import path.

```Rust
// File: src/auth/middleware.rs
// Contains: import { utils } from '../utils'
let resolved = resolve_local_import(
    "src/auth/middleware.rs",
    "../utils",
    "."
)?;
```

--------------------------------

### Build with Real Embeddings

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/configuration.md

Example of building the project with real embeddings enabled, requiring ONNX Runtime.

```bash
cargo build --release --features semantiq-embeddings/onnx
```

--------------------------------

### POST /find-refs Request Example

Source: https://github.com/so-keyldzn/semantiq/blob/main/_autodocs/http-api.md

Example of a POST request to the /find-refs endpoint to find references to a symbol.

```http
POST /find-refs HTTP/1.1
Content-Type: application/json

{
  "symbol": "DatabaseConnection",
  "limit": 50
}
```