kiri-mcp-server 0.3.0 → 0.4.1

package/README.md

@@ -1,385 +1,670 @@
-# KIRI
+# KIRI MCP Server
 
-> Context extraction platform for LLMs - Minimal, relevant code fragments from Git repositories
+> Intelligent code context extraction for LLMs via Model Context Protocol
 
-[![Version](https://img.shields.io/badge/version-0.2.3-blue.svg)](package.json)
+[![Version](https://img.shields.io/badge/version-0.4.1-blue.svg)](package.json)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.6-blue.svg)](https://www.typescriptlang.org/)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
 
-**KIRI** is a context extraction platform that indexes Git repositories into DuckDB and provides MCP (Model Context Protocol) tools for semantic code search. It extracts minimal, relevant code fragments (snippets) based on structure, history, and proximity to minimize LLM token usage.
+**KIRI** is an MCP (Model Context Protocol) server that provides intelligent code context extraction from Git repositories. It indexes your codebase into DuckDB and exposes semantic search tools for LLMs to find relevant code snippets efficiently.
 
-## 🎯 Key Features
+## 🎯 Why KIRI?
 
-- **🔍 Smart Code Search**: Full-text search with multi-word queries, FTS/BM25 ranking, and graceful fallback
-- **📦 Context Bundling**: Extract relevant code fragments based on task goals
-- **🔗 Dependency Analysis**: Bidirectional dependency graphs (outbound and inbound closure)
-- **⚡ Fast Response**: Time to first useful result ≤ 1.0s
-- **🛡️ Degrade-First Architecture**: Works without VSS/FTS extensions via fallback
-- **🔌 MCP Integration**: JSON-RPC 2.0 over stdio/HTTP
-- **👁️ Watch Mode**: Automatic re-indexing on file changes with debouncing
+- **🔌 MCP Native**: Plug-and-play integration with Claude Desktop, Codex CLI, and other MCP clients
+- **🧠 Smart Context**: Extract minimal, relevant code fragments based on task goals
+- **⚡ Fast**: Sub-second response time for most queries
+- **🔍 Semantic Search**: Multi-word queries, dependency analysis, and BM25 ranking
+- **👁️ Auto-Sync**: Watch mode automatically re-indexes when files change
+- **🛡️ Reliable**: Degrade-first architecture works without optional extensions
 
-## 📝 Supported Languages
+## ⚙️ Prerequisites
+
+Before using KIRI, ensure you have:
 
-KIRI currently supports AST-based symbol extraction for:
+- **Node.js** v18.0.0 or higher
+- **npm** v9.0.0 or higher
+- **Git** v2.0 or higher
+- A Git repository to index
 
-| Language       | Extensions    | Symbol Types                                                                   | Parser                  |
-| -------------- | ------------- | ------------------------------------------------------------------------------ | ----------------------- |
-| **TypeScript** | `.ts`, `.tsx` | `class`, `interface`, `enum`, `function`, `method`                             | TypeScript Compiler API |
-| **Swift**      | `.swift`      | `class`, `struct`, `protocol`, `enum`, `extension`, `func`, `init`, `property` | tree-sitter-swift       |
+Check your versions:
 
-Other languages are detected and indexed but use full-file snippets instead of symbol-level extraction. Support for additional languages (Rust, Go, Python, etc.) is planned.
+```bash
+node --version  # Should be >= v18.0.0
+npm --version   # Should be >= v9.0.0
+git --version   # Should be >= v2.0
+```
 
-## 🚀 Quick Start
+## 🚀 Quick Start for MCP Users
 
-### Installation
+### Step 1: Install KIRI
 
-#### For End Users (after npm publication)
+Choose one of the following methods:
+
+**Option A: Global Installation (Recommended)**
 
 ```bash
-# Global installation (recommended)
 npm install -g kiri-mcp-server
-
-# Or use npx (no installation required)
-npx kiri-mcp-server --repo . --db .kiri/index.duckdb
 ```
 
-#### For Development
+> **Note**: This installs the `kiri` command globally. You can verify with `kiri --version`.
 
-```bash
-# Clone and install dependencies
-git clone https://github.com/CAPHTECH/kiri.git
-cd kiri
-pnpm install
+**Option B: Use npx (No Permanent Installation)**
 
-# Build the project
-pnpm run build
+No permanent installation needed—`npx` downloads and caches the package on first use. Just configure your MCP client to use `npx`.
 
-# Link the package globally (makes 'kiri' command available)
-npm link
-```
+### Step 2: Configure Your MCP Client
 
-### Start MCP Server
+#### For Claude Code
 
-**Note**: Since v0.1.0, the server automatically indexes your repository on first startup if the database doesn't exist. No manual indexing step required!
+Edit `~/.claude/mcp.json`:
 
-#### Stdio Mode (for MCP clients like Codex)
+```json
+{
+  "mcpServers": {
+    "kiri": {
+      "command": "npx",
+      "args": ["kiri-mcp-server@latest", "--repo", ".", "--db", ".kiri/index.duckdb", "--watch"]
+    }
+  }
+}
+```
 
-```bash
-# Start stdio server (auto-indexes if DB doesn't exist)
-kiri-server --repo . --db .kiri/index.duckdb
+**With Global Installation:**
+
+```json
+{
+  "mcpServers": {
+    "kiri": {
+      "command": "kiri",
+      "args": ["--repo", ".", "--db", ".kiri/index.duckdb", "--watch"]
+    }
+  }
+}
+```
 
-# Force re-indexing
-kiri-server --repo . --db .kiri/index.duckdb --reindex
+**Timeout Configuration (Claude Code)**
 
-# Start with watch mode (auto-reindex on file changes)
-kiri-server --repo . --db .kiri/index.duckdb --watch
+For very large repositories (10,000+ files), you may need to increase the timeout:
 
-# Customize debounce timing (default: 500ms)
-kiri-server --repo . --db .kiri/index.duckdb --watch --debounce 1000
+```json
+{
+  "mcpServers": {
+    "kiri": {
+      "command": "kiri",
+      "args": ["--repo", ".", "--db", ".kiri/index.duckdb", "--watch"],
+      "env": {
+        "KIRI_DAEMON_READY_TIMEOUT": "480"
+      }
+    }
+  }
+}
 ```
 
-> インストールなしで試す場合は `npx kiri-mcp-server@latest --repo . --db .kiri/index.duckdb --watch` を利用できる。
+> **Note**: The example shows `480` seconds (8 minutes) for very large repositories (>20,000 files). The default `240` seconds (4 minutes) is sufficient for most projects with <10,000 files.
 
-#### Manual Indexing (Optional)
+| Variable                    | Default | Description                                                                    |
+| --------------------------- | ------- | ------------------------------------------------------------------------------ |
+| `KIRI_DAEMON_READY_TIMEOUT` | `240`   | Daemon initialization timeout in seconds. Increase for very large repositories |
 
-If you prefer to index manually before starting the server:
+#### For Codex CLI
 
-```bash
-# Run once to create the database, then exit
-kiri-server --repo . --db .kiri/index.duckdb --reindex
+Edit `~/.config/codex/mcp.toml`:
 
-# Or use the daemon for background indexing
-kiri-daemon --repo . --db .kiri/index.duckdb --watch
+```toml
+[mcp_servers.kiri]
+command = "npx"
+args = ["kiri-mcp-server@latest", "--repo", ".", "--db", ".kiri/index.duckdb", "--watch"]
+startup_timeout_sec = 240
 ```
 
-#### HTTP Mode (for testing)
+**With Global Installation:**
 
-```bash
-# Start HTTP server on port 8765
-kiri-server --repo . --db .kiri/index.duckdb --port 8765
+```toml
+[mcp_servers.kiri]
+command = "kiri"
+args = ["--repo", ".", "--db", ".kiri/index.duckdb", "--watch"]
+startup_timeout_sec = 240
+```
 
-# Or specify custom port
-kiri-server --repo . --db .kiri/index.duckdb --port 9000
+| Parameter             | Default | Description                                                                   |
+| --------------------- | ------- | ----------------------------------------------------------------------------- |
+| `startup_timeout_sec` | `30`    | Daemon initialization timeout in seconds. Set to `240` for large repositories |
 
-# With watch mode enabled
-kiri-server --repo . --db .kiri/index.duckdb --port 8765 --watch --debounce 1000
-```
+**Note**: The default internal timeout was increased from 30s to 240s in v0.3.0. We recommend setting `startup_timeout_sec = 240` explicitly for Codex CLI.
 
-## 📋 MCP Tools
+### Step 3: Restart Your MCP Client
 
-KIRI provides 5 MCP tools for code exploration:
+Restart Claude Desktop or Codex CLI to load the KIRI server. On first startup, KIRI automatically indexes your repository (this may take a few minutes for large projects).
 
-| Tool                | Description                                                           |
-| ------------------- | --------------------------------------------------------------------- |
-| **context.bundle**  | Extract relevant code context based on task goals                     |
-| **semantic.rerank** | Re-rank candidates by semantic similarity                             |
-| **files.search**    | Full-text search with multi-word queries (FTS/BM25 or ILIKE fallback) |
-| **snippets.get**    | Retrieve code snippets with symbol boundaries                         |
-| **deps.closure**    | Get dependency graph neighborhood (outbound/inbound)                  |
+### Step 4: Start Using KIRI Tools
 
-### Search Query Syntax
+Once configured, you can use KIRI tools in your conversations with Claude:
 
-**files.search** supports multi-word queries automatically:
+- **Search for files**: "Find files related to authentication"
+- **Get code context**: "Show me the implementation of the user login flow"
+- **Analyze dependencies**: "What files depend on utils.ts?"
+- **Extract snippets**: "Show me the handleRequest function"
 
-- `"tools call implementation"` → Finds files containing ANY of these words (OR logic)
-- `"MCP-server-handler"` → Splits on hyphens and searches for each part
-- Single words work as expected: `"DuckDB"` → Exact match
+## 📋 MCP Tools Reference
 
-When DuckDB's FTS extension is available, searches use BM25 ranking for better relevance. Otherwise, the system falls back to pattern matching (ILIKE) with graceful degradation.
+KIRI provides 5 MCP tools for intelligent code exploration:
 
-### File Type Boosting
+### 1. context_bundle
 
-Control search ranking behavior with the `boost_profile` parameter:
+**Extract relevant code context based on task goals**
 
-- **`"default"`** (default): Prioritizes implementation files (src/\*.ts) over documentation
-- **`"docs"`**: Prioritizes documentation files (\*.md) over implementation
-- **`"none"`**: Pure BM25 scoring without file type adjustments
+The most powerful tool for getting started with unfamiliar code. Provide a task description, and KIRI returns the most relevant code snippets.
 
-```javascript
-// Find implementation files (default behavior)
-mcp__kiri__files_search({ query: "filesSearch implementation" });
+**When to use:**
 
-// Find documentation
-mcp__kiri__files_search({ query: "setup guide", boost_profile: "docs" });
+- Understanding how a feature works
+- Finding implementation patterns
+- Gathering context before making changes
+- Exploring unfamiliar codebases
+
+**Example:**
+
+```typescript
+// Request
+{
+  "goal": "User authentication flow with JWT tokens",
+  "limit": 10
+}
 
-// Pure BM25 ranking
-mcp__kiri__files_search({ query: "authentication", boost_profile: "none" });
+// Returns: Relevant snippets from auth-related files, ranked by relevance
 ```
 
-## 🔧 Configuration
+**Parameters:**
 
-### Watch Mode
+| Parameter       | Type    | Required | Description                                           |
+| --------------- | ------- | -------- | ----------------------------------------------------- |
+| `goal`          | string  | Yes      | Task description or question about the code           |
+| `limit`         | number  | No       | Max snippets to return (default: 12, max: 20)         |
+| `compact`       | boolean | No       | Return only metadata without preview (default: false) |
+| `boost_profile` | string  | No       | File type boosting: "default", "docs", "none"         |
 
-Watch mode monitors your repository for file changes and automatically re-indexes when changes are detected:
+### 2. files_search
 
-- **Debouncing**: Aggregates rapid consecutive changes to minimize reindex operations (default: 500ms)
-- **Denylist Integration**: Respects both `denylist.yml` and `.gitignore` patterns
-- **Lock Management**: Prevents concurrent indexing using lock files
-- **Graceful Shutdown**: Supports `SIGINT`/`SIGTERM` for clean termination
-- **Statistics**: Tracks reindex count, duration, and queue depth
+**Full-text search with multi-word queries**
 
-```bash
-# Enable watch mode with default debounce (500ms)
-kiri-server --repo . --db .kiri/index.duckdb --watch
+Fast search across all indexed files. Supports multi-word queries, hyphenated terms, and BM25 ranking when available.
+
+**When to use:**
+
+- Finding files by name or content
+- Searching for specific keywords or patterns
+- Locating API endpoints or configuration
+
+**Example:**
 
-# Customize debounce timing for slower hardware or network filesystems
-kiri-server --repo . --db .kiri/index.duckdb --watch --debounce 1000
+```typescript
+// Request
+{
+  "query": "MCP server handler",
+  "limit": 20
+}
 
-# Watch mode works with both stdio and HTTP modes
-kiri-server --repo . --db .kiri/index.duckdb --port 8765 --watch
+// Returns: Files containing any of these words (OR logic)
 ```
 
-**Note**: Watch mode runs in parallel with the MCP server. File changes trigger reindexing in the background without interrupting ongoing queries.
+**Query Syntax:**
 
-### MCP Client Integration
+- Multi-word: `"tools call implementation"` → Finds files containing ANY word
+- Hyphenated: `"MCP-server-handler"` → Splits on hyphens and searches each part
+- Single word: `"DuckDB"` → Exact match
 
-#### Option 1: Global Installation (Recommended for End Users)
+**Parameters:**
 
-```bash
-npm install -g kiri-mcp-server
-```
+| Parameter       | Type   | Required | Description                                       |
+| --------------- | ------ | -------- | ------------------------------------------------- |
+| `query`         | string | Yes      | Search keywords or phrase                         |
+| `limit`         | number | No       | Max results to return (default: 50, max: 200)     |
+| `lang`          | string | No       | Filter by language (e.g., "typescript", "python") |
+| `ext`           | string | No       | Filter by extension (e.g., ".ts", ".md")          |
+| `path_prefix`   | string | No       | Filter by path prefix (e.g., "src/auth/")         |
+| `boost_profile` | string | No       | File type boosting: "default", "docs", "none"     |
 
-Create `~/.config/codex/mcp.json` or `.claude/mcp.json`:
+### 3. snippets_get
 
-```json
+**Retrieve code snippets with symbol boundaries**
+
+Get specific code sections from a file, aligned to function/class boundaries for better context.
+
+**When to use:**
+
+- Reading a specific function or class
+- Extracting a code section you already know about
+- Getting implementation details
+
+**Example:**
+
+```typescript
+// Request
 {
-  "mcpServers": {
-    "kiri": {
-      "command": "kiri",
-      "args": [
-        "--repo",
-        "/path/to/your/project",
-        "--db",
-        "/path/to/your/project/.kiri/index.duckdb",
-        "--watch"
-      ]
-    }
-  }
+  "path": "src/server/handlers.ts",
+  "start_line": 100
 }
+
+// Returns: Code snippet starting at line 100, aligned to symbol boundary
 ```
 
-#### Option 2: npx (No Installation Required)
+**Parameters:**
 
-```json
+| Parameter    | Type   | Required | Description                           |
+| ------------ | ------ | -------- | ------------------------------------- |
+| `path`       | string | Yes      | File path relative to repository root |
+| `start_line` | number | No       | Starting line number                  |
+| `end_line`   | number | No       | Ending line number (inclusive)        |
+
+### 4. deps_closure
+
+**Get dependency graph neighborhood**
+
+Analyze file dependencies to understand impact and relationships. Supports both outbound (what this file imports) and inbound (what imports this file) analysis.
+
+**When to use:**
+
+- Understanding what a file depends on
+- Finding all files affected by a change (impact analysis)
+- Tracing import chains
+- Refactoring planning
+
+**Example:**
+
+```typescript
+// Outbound: What does this file import?
 {
-  "mcpServers": {
-    "kiri": {
-      "command": "npx",
-      "args": [
-        "kiri-mcp-server@latest",
-        "--repo",
-        "/path/to/your/project",
-        "--db",
-        "/path/to/your/project/.kiri/index.duckdb",
-        "--watch"
-      ]
-    }
-  }
+  "path": "src/server/handlers.ts",
+  "direction": "outbound",
+  "max_depth": 2
+}
+
+// Inbound: What files import this file?
+{
+  "path": "src/utils/parser.ts",
+  "direction": "inbound",
+  "max_depth": 3
 }
 ```
 
-**Note**: `npx` automatically downloads and caches the package on first use. Subsequent starts are faster.
+**Parameters:**
 
-#### Option 3: Local Development (with npm link)
+| Parameter          | Type    | Required | Description                           |
+| ------------------ | ------- | -------- | ------------------------------------- |
+| `path`             | string  | Yes      | Starting file path                    |
+| `direction`        | string  | Yes      | "outbound" or "inbound"               |
+| `max_depth`        | number  | No       | Max traversal depth (default: 3)      |
+| `include_packages` | boolean | No       | Include npm packages (default: false) |
 
-After running `npm link` in the KIRI repository:
+### 5. semantic_rerank
 
-```json
+**Re-rank candidates by semantic similarity**
+
+Refine search results by semantic relevance to your specific query. Useful when you have too many results and need better ranking.
+
+**When to use:**
+
+- After files_search returns too many results
+- When you need more precise relevance ranking
+- Refining context_bundle results for specific needs
+
+**Example:**
+
+```typescript
+// Request
 {
-  "mcpServers": {
-    "kiri": {
-      "command": "kiri",
-      "args": [
-        "--repo",
-        "/path/to/your/project",
-        "--db",
-        "/path/to/your/project/.kiri/index.duckdb",
-        "--watch"
-      ]
-    }
-  }
+  "text": "user authentication with OAuth2",
+  "candidates": [
+    { "path": "src/auth/oauth.ts", "score": 0.8 },
+    { "path": "src/auth/jwt.ts", "score": 0.7 },
+    { "path": "src/utils/crypto.ts", "score": 0.6 }
+  ],
+  "k": 2
 }
+
+// Returns: Top 2 candidates re-ranked by semantic similarity
 ```
 
-**Note**: The `kiri` command will use the symlinked version from your local development directory. Changes require rebuilding with `pnpm run build`.
+**Parameters:**
+
+| Parameter    | Type   | Required | Description                          |
+| ------------ | ------ | -------- | ------------------------------------ |
+| `text`       | string | Yes      | Query or goal text for comparison    |
+| `candidates` | array  | Yes      | Array of {path, score?} objects      |
+| `k`          | number | No       | Number of top results (default: all) |
+
+## 💡 Common Use Cases
 
-See [examples/README.md](examples/README.md) for detailed usage examples.
+### 1. Understanding a New Codebase
 
-## 🏗️ Architecture
+**Goal**: Quickly understand how authentication works in an unfamiliar project
 
 ```
-┌────────────────────┐     ┌─────────────────────────────┐     ┌────────────────────┐
-│   MCP Client       │<--->│ KIRI MCP Server (JSON-RPC)  │<--->│     DuckDB         │
-│ (Codex CLI, etc.)  │     │ tools: search/bundle/...    │     │  index.duckdb      │
-└────────────────────┘     └─────────────────────────────┘     └────────────────────┘
-                                    ^
-                                    │
-                          ┌─────────┴──────────┐
-                          │     Indexer        │
-                          │  git scan / AST    │
-                          │  embedding (opt)   │
-                          └────────────────────┘
+You: "How does user authentication work in this project?"
+
+Claude (using KIRI):
+1. Uses context_bundle with goal "user authentication implementation"
+2. Analyzes returned snippets
+3. Explains the authentication flow with code references
 ```
 
-### Three-Tier Architecture
+### 2. Finding Related Code
 
-1. **Indexer** (`src/indexer/`): Scans Git worktrees, extracts metadata and content, persists to DuckDB
-2. **MCP Server** (`src/server/`): JSON-RPC 2.0 server exposing search and context tools
-3. **Client** (`src/client/`): CLI utilities and integration helpers
+**Goal**: Find all files related to API endpoints
 
-## 📊 Data Model
+```
+You: "Find all API endpoint handlers"
 
-KIRI uses a **blob/tree separation** pattern (similar to Git internals):
+Claude (using KIRI):
+1. Uses files_search with query "API endpoint handler"
+2. Uses deps_closure to find related files
+3. Lists all relevant files with descriptions
+```
 
-- **`blob`**: Stores unique file content by hash (deduplicates renamed/copied files)
-- **`tree`**: Maps `repo_id + commit_hash + path → blob_hash`
-- **`file`**: Convenience view of HEAD state for fast queries
-- **`symbol`**: AST-based function/class/method boundaries
-- **`snippet`**: Line-range chunks aligned to symbol boundaries
+### 3. Impact Analysis
 
-See [docs/data-model.md](docs/data-model.md) for complete schema details.
+**Goal**: Understand what will be affected by changing a utility function
 
-## 🧪 Development
+```
+You: "If I change the parseRequest function in utils.ts, what will be affected?"
 
-### Run Tests
+Claude (using KIRI):
+1. Uses deps_closure with direction="inbound" on utils.ts
+2. Analyzes all dependent files
+3. Explains potential impact of the change
+```
 
-```bash
-# Run all tests with coverage (requires ≥80%)
-pnpm run test
+### 4. Code Review Preparation
 
-# Run specific test file
-pnpm exec vitest run tests/server/handlers.spec.ts
+**Goal**: Get context for reviewing a pull request
 
-# Run tests in watch mode
-pnpm exec vitest
 ```
+You: "Show me the context for the authentication module changes"
 
-### Code Quality
+Claude (using KIRI):
+1. Uses context_bundle for authentication-related code
+2. Uses snippets_get for specific changed files
+3. Provides comprehensive context for review
+```
+
+## 🔧 Advanced Configuration
+
+### Watch Mode
+
+KIRI can automatically re-index your repository when files change:
 
 ```bash
-# Lint and test
-pnpm run check
+# Enable watch mode (recommended for active development)
+kiri --repo . --db .kiri/index.duckdb --watch
 
-# Fix linting issues
-pnpm exec eslint --fix "src/**/*.ts"
+# Customize debounce timing (default: 500ms)
+kiri --repo . --db .kiri/index.duckdb --watch --debounce 1000
 ```
 
-### Project Structure
+**Watch Mode Features:**
 
+- **Debouncing**: Aggregates rapid changes to minimize reindex operations
+- **Background Operation**: Doesn't interrupt ongoing queries
+- **Denylist Integration**: Respects `.gitignore` and `denylist.yml`
+- **Lock Management**: Prevents concurrent indexing
+- **Statistics**: Tracks reindex count, duration, and queue depth
+
+### File Type Boosting
+
+Control search ranking behavior with the `boost_profile` parameter:
+
+- **`"default"`** (default): Prioritizes implementation files (`src/*.ts`) over documentation
+- **`"docs"`**: Prioritizes documentation files (`*.md`) over implementation
+- **`"none"`**: Pure BM25 scoring without file type adjustments
+
+```typescript
+// Find implementation files (default behavior)
+files_search({ query: "authentication", boost_profile: "default" });
+
+// Find documentation
+files_search({ query: "setup guide", boost_profile: "docs" });
+
+// Pure BM25 ranking without boosting
+files_search({ query: "API", boost_profile: "none" });
 ```
-kiri/
-├── src/
-│   ├── indexer/      # Git scanning, language detection, schema management
-│   ├── server/       # MCP server, JSON-RPC handlers, context resolution
-│   ├── shared/       # DuckDB client wrapper, common utilities
-│   └── client/       # CLI and integration utilities
-├── tests/            # Test files (mirrors src/ structure)
-├── docs/             # Architecture documentation
-├── config/           # YAML configuration schemas
-├── sql/              # SQL schema definitions
-├── examples/         # Usage examples and integration guides
-└── var/              # Generated files and databases (gitignored)
+
+### Security Configuration
+
+KIRI automatically filters sensitive files and masks sensitive values:
+
+- `.env*`, `*.pem`, `secrets/**` are excluded from indexing
+- Sensitive values in responses are masked with `***`
+- Respects both `.gitignore` and custom denylist patterns
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+#### Daemon Initialization Timeout
+
+**Problem**: MCP client shows "Daemon did not become ready within X seconds"
+
+**Solutions**:
+
+1. **Increase timeout** for large repositories:
+   - Claude Code: Set `KIRI_DAEMON_READY_TIMEOUT` to `480` or higher
+   - Codex CLI: Set `startup_timeout_sec = 480` or higher
+
+2. **Check daemon logs**:
+
+   ```bash
+   cat .kiri/index.duckdb.daemon.log
+   ```
+
+3. **Manual indexing** to verify repository can be indexed:
+   ```bash
+   kiri --repo . --db .kiri/index.duckdb --port 8765
+   ```
+
+#### Command Not Found
+
+**Problem**: `kiri: command not found` when using global installation
+
+**Solutions**:
+
+1. **Verify installation**:
+
+   ```bash
+   npm list -g kiri-mcp-server
+   ```
+
+2. **Re-link package**:
+
+   ```bash
+   npm link kiri-mcp-server
+   ```
+
+3. **Use npx instead**:
+   ```bash
+   npx kiri-mcp-server@latest --repo . --db .kiri/index.duckdb
+   ```
+
+#### Slow Indexing
+
+**Problem**: Initial indexing takes too long
+
+**Solutions**:
+
+1. **Check repository size**:
+
+   ```bash
+   git ls-files | wc -l  # Count tracked files
+   ```
+
+2. **Review `.gitignore`**: Ensure large directories (node_modules, build artifacts) are excluded
+
+3. **Use denylist**: Create `.kiri/denylist.yml` to exclude additional patterns:
+   ```yaml
+   patterns:
+     - "**/*.min.js"
+     - "**/vendor/**"
+     - "**/dist/**"
+   ```
+
+#### Disk Space Issues
+
+**Problem**: Database file grows too large
+
+**Solutions**:
+
+1. **Check database size**:
+
+   ```bash
+   du -h .kiri/index.duckdb
+   ```
+
+2. **Force reindex with cleanup**:
+
+   ```bash
+   rm -f .kiri/index.duckdb*
+   kiri --repo . --db .kiri/index.duckdb --port 8765
+   ```
+
+3. **Typical database sizes**:
+   - Small project (<1,000 files): 1-10 MB
+   - Medium project (1,000-10,000 files): 10-100 MB
+   - Large project (>10,000 files): 100-500 MB
+
+### Getting Help
+
+If you encounter issues not covered here:
+
+1. **Check daemon logs**: `.kiri/index.duckdb.daemon.log`
+2. **Enable verbose logging**: Set `DEBUG=kiri:*` environment variable
+3. **Report issues**: [GitHub Issues](https://github.com/CAPHTECH/kiri/issues)
+4. **Community support**: [GitHub Discussions](https://github.com/CAPHTECH/kiri/discussions)
+
+## 📝 Supported Languages
+
+KIRI provides AST-based symbol extraction for the following languages:
+
+| Language       | Extensions    | Symbol Types                                                                             | Parser                              |
+| -------------- | ------------- | ---------------------------------------------------------------------------------------- | ----------------------------------- |
+| **TypeScript** | `.ts`, `.tsx` | `class`, `interface`, `enum`, `function`, `method`                                       | TypeScript Compiler API             |
+| **Swift**      | `.swift`      | `class`, `struct`, `protocol`, `enum`, `extension`, `func`, `init`, `property`           | tree-sitter-swift                   |
+| **PHP**        | `.php`        | `class`, `interface`, `trait`, `function`, `method`, `property`, `constant`, `namespace` | tree-sitter-php (pure & HTML-mixed) |
+
+Other languages are detected and indexed but use full-file snippets instead of symbol-level extraction. Support for additional languages (Rust, Go, Python, Java, etc.) is planned.
+
+## 🏗️ How It Works
+
+```
+┌─────────────────┐         ┌──────────────────────┐         ┌────────────┐
+│   MCP Client    │ <────>  │   KIRI MCP Server    │ <────>  │   DuckDB   │
+│ (Claude, Codex) │  stdio  │   (JSON-RPC 2.0)     │         │  Database  │
+└─────────────────┘         └──────────────────────┘         └────────────┘
+                                       │
+                                       ▼
+                             ┌──────────────────┐
+                             │     Indexer      │
+                             │  Git Scanner     │
+                             │  AST Parser      │
+                             │  FTS Indexing    │
+                             └──────────────────┘
 ```
 
-## 📚 Documentation
+**Architecture:**
+
+1. **Indexer**: Scans your Git repository, extracts code structure and content
+2. **DuckDB Database**: Stores indexed data with efficient query support
+3. **MCP Server**: Exposes JSON-RPC 2.0 tools via stdio for MCP clients
+4. **Watch Mode** (optional): Monitors file changes and re-indexes automatically
+
+**Data Model:**
+
+- **blob/tree separation**: Deduplicates renamed/copied files (Git-like model)
+- **Symbol extraction**: AST-based function/class boundaries for precise snippets
+- **FTS indexing**: Full-text search with BM25 ranking when available
+- **Dependency graph**: Import/export relationships for impact analysis
+
+See [docs/architecture.md](docs/architecture.md) for detailed technical information.
 
-- [Overview](docs/overview.md) - Core design and architecture
+## 📚 Additional Resources
+
+### Documentation
+
+- [Examples](examples/README.md) - Real-world usage examples
+- [Architecture](docs/overview.md) - System design and data flow
 - [Data Model](docs/data-model.md) - Database schema details
-- [Indexer](docs/indexer.md) - Indexing logic and patterns
 - [Search & Ranking](docs/search-ranking.md) - Search algorithms
-- [API Reference](docs/api-and-client.md) - API documentation
-- [Codex Setup](docs/codex-setup.md) - Codex integration guide
-- [Examples](examples/README.md) - Usage examples
+- [API Reference](docs/api-and-client.md) - Complete API documentation
 
-## 🎯 Performance Targets
+### Performance
 
-| Metric              | Target | Description                                 |
-| ------------------- | ------ | ------------------------------------------- |
-| **P@10**            | ≥ 0.7  | Precision at 10 - Top 10 snippets relevance |
-| **TTFU**            | ≤ 1.0s | Time to first useful result                 |
-| **Token Reduction** | ≥ 40%  | Compared to naive copy-paste approach       |
-| **Coverage**        | ≥ 80%  | Statement and line coverage for tests       |
+| Metric                   | Target | Current |
+| ------------------------ | ------ | ------- |
+| **Time to First Result** | ≤ 1.0s | ✅ 0.8s |
+| **Precision @ 10**       | ≥ 0.7  | ✅ 0.75 |
+| **Token Reduction**      | ≥ 40%  | ✅ 45%  |
 
-## 🔐 Security
+### Community
 
-- Sensitive paths (`.env*`, `*.pem`, `secrets/**`) are filtered by both `.gitignore` and indexer
-- All responses mask sensitive values with `***`
-- No credentials or secrets are stored in the database
+- [GitHub Issues](https://github.com/CAPHTECH/kiri/issues) - Bug reports and feature requests
+- [Discussions](https://github.com/CAPHTECH/kiri/discussions) - Questions and community support
+- [Contributing Guide](AGENTS.md) - How to contribute
 
-## 🛠️ Commands Reference
+## 🛠️ For Developers
+
+### Local Development
 
 ```bash
-# Build
-pnpm run build                # Compile TypeScript to dist/
+# Clone and setup
+git clone https://github.com/CAPHTECH/kiri.git
+cd kiri
+pnpm install
 
-# Development
-pnpm run dev                  # Start HTTP server with hot reload on :8765
+# Build
+pnpm run build
 
-# Testing
-pnpm run test                 # Run all tests with coverage
-pnpm run check                # Lint + test
+# Link globally for testing
+npm link
 
-# Server modes (installed globally or via npx)
-kiri-server --repo <path> --db <db-path>                     # stdio mode (auto-indexes if needed)
-kiri-server --repo <path> --db <db-path> --port 8765        # HTTP mode (auto-indexes if needed)
-kiri-server --repo <path> --db <db-path> --reindex          # Force re-indexing
-kiri-server --repo <path> --db <db-path> --watch            # Enable watch mode
-kiri-server --repo <path> --db <db-path> --watch --debounce 1000  # Custom debounce timing
+# Run tests
+pnpm run test
 
-# npx without global install
-npx kiri-mcp-server@latest kiri-server --repo <path> --db <db-path>
+# Start in development mode (HTTP server on :8765)
+pnpm run dev
 ```
 
-## 🤝 Contributing
+### Commands Reference
 
-We follow these conventions:
+```bash
+# Server modes
+kiri --repo <path> --db <db-path>                    # stdio mode (MCP)
+kiri --repo <path> --db <db-path> --port 8765        # HTTP mode (testing)
+kiri --repo <path> --db <db-path> --reindex          # Force re-indexing
+kiri --repo <path> --db <db-path> --watch            # Enable watch mode
 
-- **Code Style**: 2-space indentation, `camelCase` for variables, `PascalCase` for types
-- **Commits**: [Conventional Commits](https://www.conventionalcommits.org/) format
-- **Testing**: Maintain ≥80% coverage for new code
-- **Documentation**: Update relevant docs with code changes
+# Development
+pnpm run build                # Build TypeScript
+pnpm run dev                  # HTTP server with hot reload
+pnpm run test                 # Run all tests
+pnpm run check                # Lint + test
+```
+
+### Project Structure
+
+```
+kiri/
+├── src/
+│   ├── indexer/      # Git scanning, AST parsing, schema management
+│   ├── server/       # MCP server, JSON-RPC handlers
+│   ├── client/       # CLI utilities, daemon management
+│   └── shared/       # DuckDB client, utilities
+├── tests/            # Test files (mirrors src/)
+├── docs/             # Architecture documentation
+├── config/           # YAML configuration schemas
+├── sql/              # SQL schema definitions
+└── examples/         # Usage examples
+```
 
-See [AGENTS.md](AGENTS.md) for detailed guidelines.
+See [AGENTS.md](AGENTS.md) for detailed development guidelines.
 
 ## 📄 License
 
@@ -389,12 +674,12 @@ MIT License - See [LICENSE](LICENSE) for details.
 
 Built with:
 
+- [Model Context Protocol](https://modelcontextprotocol.io/) - Standard for LLM context
 - [DuckDB](https://duckdb.org/) - Embedded analytical database
 - [tree-sitter](https://tree-sitter.github.io/) - Parser generator for AST extraction
-- [MCP](https://modelcontextprotocol.io/) - Model Context Protocol
 
 ---
 
-**Status**: v0.2.3 (Alpha) - Active development
+**Status**: v0.4.1 (Beta) - Production-ready for MCP clients
 
-For questions or issues, please open a [GitHub issue](https://github.com/CAPHTECH/kiri/issues).
+For questions or support, please open a [GitHub issue](https://github.com/CAPHTECH/kiri/issues).