diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..b0ca18b
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,73 @@
+## 📋 Description
+
+<!-- Briefly describe what this PR does and why -->
+
+## 🔗 Related Issues
+
+<!-- Link to related GitHub issues -->
+Closes #
+
+## 🧪 Testability Checklist
+
+<!-- Check all that apply -->
+
+- [ ] Pure functions extracted to `utils/` modules
+- [ ] Utilities achieve 100% coverage (statements & functions)
+- [ ] No `!` non-null assertions (use guard clauses or optional chaining)
+- [ ] Modules organized by domain (not generic "utils")
+- [ ] Each module < 200 lines
+- [ ] Atomic commits with clear dependencies
+
+## ✅ Testing
+
+<!-- Describe testing approach -->
+
+- [ ] Unit tests added/updated
+- [ ] Integration tests added/updated
+- [ ] Coverage meets targets:
+  - Pure utilities: 100%
+  - Integration: >80%
+  - CLI/UI: >60%
+- [ ] All tests passing locally
+
+## 📊 Coverage
+
+<!-- Paste coverage report for changed files -->
+
+```
+Before: X% statements, Y% branches, Z% functions
+After:  X% statements, Y% branches, Z% functions
+```
+
+## 🏗️ Architecture
+
+<!-- If refactoring, describe the structure -->
+
+- [ ] Follows dependency order (foundation → dependent → integration)
+- [ ] Barrel exports for clean imports
+- [ ] Clear separation of pure/impure code
+
+## 📝 Documentation
+
+- [ ] Updated README if public API changed
+- [ ] Added JSDoc for public functions
+- [ ] Updated CHANGELOG (if applicable)
+
+## 🚀 Deployment
+
+- [ ] No breaking changes
+- [ ] Backward compatible
+- [ ] Database migrations (if applicable)
+
+## 📸 Screenshots
+
+<!-- If UI changes, add screenshots -->
+
+---
+
+**Commit Strategy:**
+<!-- Did you follow granular commits? -->
+- [ ] Atomic commits (each builds independently)
+- [ ] Conventional commit messages
+- [ ] Clear commit descriptions
+
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index bc74ffd..f882a17 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,6 +1,13 @@
-# Contributing to TS Monorepo
+# Contributing to Dev-Agent
 
-Thank you for considering contributing to our TypeScript monorepo! This document outlines the process for contributing and the standards we follow.
+Thank you for considering contributing to dev-agent! This document outlines the process for contributing and the standards we follow.
+
+## 🎯 **Core Values**
+
+1. **Testability First** - If it's hard to test, refactor it
+2. **Modularity** - Small, focused, reusable modules
+3. **100% Coverage on Utilities** - Pure functions should be fully tested
+4. **Atomic Commits** - Each commit should build and test independently
 
 ## Development Process
 
@@ -46,11 +53,56 @@ feat(core): add new API method for authentication
 3. Add the package to relevant workspace configurations.
 4. Update path mappings in the root `tsconfig.json`.
 
-## Testing
+## Testing & Testability
+
+### 📖 **Read First:** [TESTABILITY.md](./docs/TESTABILITY.md)
+
+Our comprehensive testability guide covers:
+- When and how to extract utilities
+- Organization patterns
+- Coverage targets
+- Real-world examples
+
+### **Quick Rules:**
+
+1. **Extract Pure Functions** to `utils/` modules
+   - ✅ DO: `utils/formatting.ts` with `formatDocument(doc: Document)`
+   - ❌ DON'T: Private methods in 500-line classes
+
+2. **Aim for 100% on Utilities**
+   - Pure functions are easy to test
+   - No mocks needed
+   - Foundation for everything else
+
+3. **No Non-Null Assertions (`!`)**
+   - Use guard clauses or optional chaining
+   - Makes code safer and more testable
+
+4. **Organize by Domain**
+   - ✅ `utils/strings.ts`, `utils/dates.ts`, `utils/validation.ts`
+   - ❌ `utils.ts` (500 lines of everything)
+
+### **Coverage Targets:**
+
+| Code Type | Target | Example |
+|-----------|--------|---------|
+| **Pure Utilities** | 100% | `formatDocument()`, `calculateCoverage()` |
+| **Integration** | >80% | `RepositoryIndexer`, `ExplorerAgent` |
+| **CLI/UI** | >60% | Command handlers, spinners |
+
+### **Before Submitting:**
+
+```bash
+# Run tests with coverage
+pnpm vitest run --coverage
+
+# Check specific package
+pnpm vitest run packages/core/src/indexer --coverage
+```
 
-- Write tests for all new features and bug fixes.
-- Run existing tests to ensure your changes don't break existing functionality.
-- Aim for good test coverage.
+- Write tests for all new features and bug fixes
+- Run existing tests to ensure your changes don't break existing functionality
+- See [TESTABILITY.md](./docs/TESTABILITY.md) for detailed guidelines
 
 ## Code Style
 
diff --git a/docs/FEATURE_TEMPLATE.md b/docs/FEATURE_TEMPLATE.md
new file mode 100644
index 0000000..4dd3b31
--- /dev/null
+++ b/docs/FEATURE_TEMPLATE.md
@@ -0,0 +1,301 @@
+# Feature Template
+
+Use this template when adding new features to ensure testability and maintainability.
+
+## 📁 Recommended Structure
+
+```
+packages/[package]/src/[feature]/
+├── index.ts              # Main feature implementation
+├── types.ts              # Type definitions
+├── [feature].test.ts     # Integration tests
+├── utils/                # Testable utilities
+│   ├── [domain1].ts      # Pure functions (foundation)
+│   ├── [domain1].test.ts # Unit tests (100% coverage)
+│   ├── [domain2].ts      # Pure functions (independent)
+│   ├── [domain2].test.ts # Unit tests (100% coverage)
+│   ├── [domain3].ts      # Dependent functions
+│   ├── [domain3].test.ts # Unit tests (100% coverage)
+│   └── index.ts          # Barrel export
+└── README.md             # Feature documentation
+```
+
+---
+
+## 📝 Step-by-Step Guide
+
+### 1. Define Types First
+
+```typescript
+// types.ts
+export interface MyFeatureConfig {
+  option1: string;
+  option2?: number;
+}
+
+export interface MyFeatureResult {
+  data: string[];
+  count: number;
+}
+
+export type MyFeatureAction = 'create' | 'update' | 'delete';
+```
+
+### 2. Extract Pure Utilities
+
+Identify reusable, testable logic:
+
+```typescript
+// utils/validation.ts (foundation - no dependencies)
+export function validateConfig(config: MyFeatureConfig): boolean {
+  return config.option1.length > 0;
+}
+
+export function isValidAction(action: string): action is MyFeatureAction {
+  return ['create', 'update', 'delete'].includes(action);
+}
+```
+
+```typescript
+// utils/validation.test.ts
+import { describe, expect, it } from 'vitest';
+import { validateConfig, isValidAction } from './validation';
+
+describe('Validation Utilities', () => {
+  describe('validateConfig', () => {
+    it('should return true for valid config', () => {
+      expect(validateConfig({ option1: 'test' })).toBe(true);
+    });
+
+    it('should return false for empty option1', () => {
+      expect(validateConfig({ option1: '' })).toBe(false);
+    });
+  });
+
+  describe('isValidAction', () => {
+    it('should return true for valid actions', () => {
+      expect(isValidAction('create')).toBe(true);
+      expect(isValidAction('update')).toBe(true);
+      expect(isValidAction('delete')).toBe(true);
+    });
+
+    it('should return false for invalid actions', () => {
+      expect(isValidAction('invalid')).toBe(false);
+    });
+  });
+});
+```
+
+### 3. More Utilities (Dependent)
+
+```typescript
+// utils/transformation.ts (depends on validation)
+import { isValidAction } from './validation';
+import type { MyFeatureAction } from '../types';
+
+export function normalizeAction(action: string): MyFeatureAction | null {
+  if (!isValidAction(action)) {
+    return null;
+  }
+  return action;
+}
+
+export function transformData(data: string[]): string {
+  return data.join(', ');
+}
+```
+
+### 4. Barrel Export
+
+```typescript
+// utils/index.ts
+export { isValidAction, validateConfig } from './validation';
+export { normalizeAction, transformData } from './transformation';
+```
+
+### 5. Main Implementation
+
+```typescript
+// index.ts
+import type { MyFeatureConfig, MyFeatureResult } from './types';
+import { normalizeAction, transformData, validateConfig } from './utils';
+
+export class MyFeature {
+  constructor(private config: MyFeatureConfig) {
+    if (!validateConfig(config)) {
+      throw new Error('Invalid configuration');
+    }
+  }
+
+  async execute(action: string, data: string[]): Promise<MyFeatureResult> {
+    // Guard clause using utility
+    const validAction = normalizeAction(action);
+    if (!validAction) {
+      throw new Error(`Invalid action: ${action}`);
+    }
+
+    // Use utility for transformation
+    const transformed = transformData(data);
+
+    // Integration logic (impure, side effects)
+    // ...
+
+    return {
+      data: [transformed],
+      count: data.length,
+    };
+  }
+}
+
+// Re-export types
+export type * from './types';
+
+// Re-export utilities for consumers
+export * from './utils';
+```
+
+### 6. Integration Tests
+
+```typescript
+// [feature].test.ts
+import { describe, expect, it } from 'vitest';
+import { MyFeature } from './index';
+
+describe('MyFeature', () => {
+  describe('constructor', () => {
+    it('should create instance with valid config', () => {
+      const feature = new MyFeature({ option1: 'test' });
+      expect(feature).toBeDefined();
+    });
+
+    it('should throw for invalid config', () => {
+      expect(() => new MyFeature({ option1: '' })).toThrow('Invalid configuration');
+    });
+  });
+
+  describe('execute', () => {
+    it('should execute valid action', async () => {
+      const feature = new MyFeature({ option1: 'test' });
+      const result = await feature.execute('create', ['a', 'b']);
+
+      expect(result.data).toEqual(['a, b']);
+      expect(result.count).toBe(2);
+    });
+
+    it('should reject invalid action', async () => {
+      const feature = new MyFeature({ option1: 'test' });
+      await expect(feature.execute('invalid', [])).rejects.toThrow('Invalid action');
+    });
+  });
+});
+```
+
+### 7. Documentation
+
+```markdown
+# My Feature
+
+Brief description of what this feature does.
+
+## Usage
+
+\`\`\`typescript
+import { MyFeature } from '@lytics/dev-agent-[package]/[feature]';
+
+const feature = new MyFeature({ option1: 'value' });
+const result = await feature.execute('create', ['data']);
+\`\`\`
+
+## API
+
+### `MyFeature`
+
+Main class for...
+
+### Utilities
+
+- `validateConfig()` - Validates configuration
+- `isValidAction()` - Type guard for actions
+- `normalizeAction()` - Normalizes action strings
+- `transformData()` - Transforms data array
+
+## Testing
+
+\`\`\`bash
+pnpm vitest run packages/[package]/src/[feature] --coverage
+\`\`\`
+
+Target: 100% coverage on utilities, >80% on integration.
+```
+
+---
+
+## ✅ Checklist
+
+Before submitting your feature:
+
+### Code Organization
+- [ ] Types defined in `types.ts`
+- [ ] Pure functions in `utils/[domain].ts`
+- [ ] Each utility module <150 lines
+- [ ] Barrel export `utils/index.ts`
+- [ ] Main implementation in `index.ts`
+
+### Testing
+- [ ] Unit tests for all utilities (100% coverage)
+- [ ] Integration tests for main implementation (>80%)
+- [ ] Edge cases covered (empty, null, errors)
+- [ ] No mocks in utility tests
+
+### Code Quality
+- [ ] No `!` non-null assertions
+- [ ] Guard clauses for validation
+- [ ] JSDoc on public functions
+- [ ] No console.log (use logger)
+
+### Commits
+- [ ] Atomic commits (each builds independently)
+- [ ] Conventional commit messages
+- [ ] Dependency order: foundation → dependent → integration
+
+---
+
+## 📚 Examples
+
+See these implementations:
+
+1. **Explorer Subagent**
+   - Path: `packages/subagents/src/explorer/`
+   - 99 tests, 100% on utilities
+   - 4 domain modules: metadata, filters, relationships, analysis
+
+2. **Repository Indexer**
+   - Path: `packages/core/src/indexer/`
+   - 87 tests on utilities
+   - 3 domain modules: language, formatting, documents
+
+3. **Subagent Coordinator**
+   - Path: `packages/subagents/src/coordinator/`
+   - Context manager, task queue, message protocol
+   - High test coverage with mocks where needed
+
+---
+
+## ❓ FAQs
+
+**Q: How do I know what to extract?**  
+A: If it's >20 lines, pure (no side effects), or reusable → extract it.
+
+**Q: Should everything be 100% coverage?**  
+A: Only pure utilities. Integration can be 80%, CLI/UI can be 60%.
+
+**Q: Can I use `!` for "impossible" cases?**  
+A: No. Use guard clauses or optional chaining. It's safer and more testable.
+
+**Q: What if my util module gets >200 lines?**  
+A: Split by domain. Example: `utils/strings.ts` and `utils/arrays.ts` instead of `utils/helpers.ts`.
+
+---
+
+**Happy coding!** 🚀
+
diff --git a/docs/TESTABILITY.md b/docs/TESTABILITY.md
new file mode 100644
index 0000000..5de7312
--- /dev/null
+++ b/docs/TESTABILITY.md
@@ -0,0 +1,350 @@
+# Testability Guidelines
+
+This document outlines our approach to writing testable, maintainable code in the dev-agent monorepo.
+
+## Philosophy
+
+> **"If it's hard to test, it's hard to use."**
+
+Testability is not just about code coverage—it's about **designing modular, reusable, and understandable code**.
+
+---
+
+## Core Principles
+
+### 1. **Extract Pure Functions**
+
+❌ **BAD: Inline logic in large classes**
+```typescript
+class MyService {
+  private formatData(data: Data): string {
+    // 50 lines of formatting logic
+  }
+  
+  private validateData(data: Data): boolean {
+    // 30 lines of validation logic
+  }
+}
+```
+
+✅ **GOOD: Extract to testable utility modules**
+```typescript
+// utils/formatting.ts
+export function formatData(data: Data): string {
+  // 50 lines of formatting logic
+}
+
+// utils/validation.ts
+export function validateData(data: Data): boolean {
+  // 30 lines of validation logic
+}
+
+// service.ts
+import { formatData } from './utils/formatting';
+import { validateData } from './utils/validation';
+
+class MyService {
+  // Uses utilities, no private implementation
+}
+```
+
+**Why?**
+- ✅ Direct unit tests (no class instantiation needed)
+- ✅ Reusable across modules
+- ✅ Tree-shakeable for bundlers
+- ✅ Easy to understand (SRP)
+
+---
+
+### 2. **Organize by Domain**
+
+❌ **BAD: Monolithic utils file**
+```
+utils.ts (500 lines)
+├── String helpers
+├── Date helpers
+├── Validation helpers
+└── Formatting helpers
+```
+
+✅ **GOOD: Domain-specific modules**
+```
+utils/
+├── strings.ts      (50 lines, 10 tests)
+├── dates.ts        (60 lines, 12 tests)
+├── validation.ts   (80 lines, 15 tests)
+├── formatting.ts   (70 lines, 13 tests)
+└── index.ts        (barrel export)
+```
+
+**Why?**
+- ✅ Clear boundaries (SRP)
+- ✅ Easy to navigate
+- ✅ Isolated testing
+- ✅ Parallel development
+
+---
+
+### 3. **100% Coverage on Utilities**
+
+Pure utility modules should have **100% coverage** as they:
+- Have no side effects
+- Are easy to test
+- Form the foundation for integration logic
+
+**Coverage Targets:**
+- **Utilities**: 100% statements, 100% functions, >90% branches
+- **Integration**: >80% statements, >70% branches
+- **CLI/UI**: >60% (harder to test, more mocks)
+
+---
+
+### 4. **No Non-Null Assertions**
+
+❌ **BAD: Using ! assertions**
+```typescript
+function process(data: Data | undefined) {
+  const result = data!.value; // Unsafe!
+}
+```
+
+✅ **GOOD: Guard clauses or optional chaining**
+```typescript
+function process(data: Data | undefined) {
+  if (!data) {
+    throw new Error('Data is required');
+  }
+  return data.value; // Type-safe
+}
+
+// Or use optional chaining
+function process(data: Data | undefined): string | undefined {
+  return data?.value;
+}
+```
+
+---
+
+### 5. **Dependency Order in Commits**
+
+When extracting utilities, commit in dependency order:
+
+```
+Commit 1: Foundation (no dependencies)
+   ↓
+Commit 2: Independent utilities
+   ↓
+Commit 3: Dependent utilities (use foundation)
+   ↓
+Commit 4: Integration (wire everything together)
+```
+
+**Example: Indexer Refactoring**
+```bash
+1. language.ts       (foundation - no deps)
+2. formatting.ts     (independent - no deps)
+3. documents.ts      (depends on formatting.ts)
+4. Integration       (update imports, remove old code)
+```
+
+---
+
+## Practical Checklist
+
+Before merging code, ask:
+
+### ✅ **Extraction Checklist**
+
+- [ ] Are private methods >20 lines? → Extract to utils
+- [ ] Is logic reusable? → Extract to utils
+- [ ] Can I test this directly? → If no, extract
+- [ ] Does this have side effects? → Separate pure/impure
+- [ ] Is this module >300 lines? → Split by domain
+
+### ✅ **Testing Checklist**
+
+- [ ] 100% coverage on pure functions
+- [ ] No mocks for utility tests
+- [ ] Integration tests for side effects
+- [ ] Edge cases covered (empty, null, boundary)
+- [ ] Error paths tested
+
+### ✅ **Organization Checklist**
+
+- [ ] Utils organized by domain (not "misc")
+- [ ] Barrel export (`index.ts`) for clean imports
+- [ ] Each module <150 lines
+- [ ] Each test file <400 lines
+- [ ] Clear dependency relationships
+
+---
+
+## Real-World Example: Explorer Subagent
+
+### **Before Refactoring:**
+```typescript
+// explorer/index.ts (380 lines)
+class ExplorerAgent {
+  private extractMetadata(result: SearchResult) { /* ... */ }
+  private matchesFileType(result: SearchResult, types: string[]) { /* ... */ }
+  private isDuplicate(rels: Rel[], file: string, line: number) { /* ... */ }
+  // 15+ helper methods inline
+}
+```
+
+**Problems:**
+- ❌ Can't test helpers directly
+- ❌ 57% function coverage
+- ❌ Hard to reuse logic
+
+### **After Refactoring:**
+```typescript
+// explorer/utils/
+// ├── metadata.ts      (54 lines, 8 tests, 100% coverage)
+// ├── filters.ts       (42 lines, 15 tests, 100% coverage)
+// ├── relationships.ts (63 lines, 16 tests, 100% coverage)
+// ├── analysis.ts      (64 lines, 27 tests, 100% coverage)
+// └── index.ts         (barrel)
+
+// explorer/index.ts (now 360 lines, cleaner)
+import { extractMetadata, matchesFileType } from './utils';
+
+class ExplorerAgent {
+  // Uses utilities, no inline helpers
+}
+```
+
+**Benefits:**
+- ✅ 99 unit tests (vs. 33 integration only)
+- ✅ 100% coverage on utilities
+- ✅ 80% function coverage overall
+- ✅ Logic reusable in CLI
+
+---
+
+## When NOT to Extract
+
+Don't extract everything blindly. Keep logic inline when:
+
+1. **Tightly coupled to class state** (uses multiple `this.*`)
+2. **Very short** (<10 lines, simple)
+3. **Used once** and not complex
+4. **Side effects required** (file I/O, network, state mutation)
+
+**Example of OK inline logic:**
+```typescript
+class Service {
+  private isInitialized(): boolean {
+    return this.state !== null; // Simple, uses this.state
+  }
+}
+```
+
+---
+
+## Tooling & Automation
+
+### **1. Pre-commit Hooks**
+```bash
+# Already configured in .husky/pre-commit
+- Biome linting (catches unused code)
+- TypeScript type checking
+- Test runs (optional, for speed)
+```
+
+### **2. CI Coverage Enforcement**
+```yaml
+# .github/workflows/ci.yml
+- name: Check Coverage
+  run: |
+    pnpm vitest run --coverage
+    # Enforce thresholds:
+    # - Utils: 100%
+    # - Integration: 80%
+```
+
+### **3. Code Review Checklist**
+Use this in PR descriptions:
+
+```markdown
+## Testability Checklist
+- [ ] Utilities extracted where appropriate
+- [ ] 100% coverage on pure functions
+- [ ] No non-null assertions (!)
+- [ ] Domain-specific organization
+- [ ] Atomic commits with clear dependencies
+```
+
+---
+
+## Migration Guide
+
+### **Step 1: Identify Candidates**
+```bash
+# Find large files with low coverage
+pnpm vitest run --coverage
+
+# Look for:
+# - Files >300 lines
+# - Coverage <80%
+# - Many private methods
+```
+
+### **Step 2: Extract Utilities**
+```bash
+# 1. Create utils/ directory
+mkdir -p src/myfeature/utils
+
+# 2. Extract by domain (foundation first)
+# 3. Write tests (aim for 100%)
+# 4. Update imports
+# 5. Remove old code
+```
+
+### **Step 3: Commit Strategy**
+```bash
+# Commit 1: Foundation utilities
+git commit -m "feat(feature): add [foundation] utilities"
+
+# Commit 2: Dependent utilities
+git commit -m "feat(feature): add [dependent] utilities"
+
+# Commit 3: Integration
+git commit -m "refactor(feature): integrate modular utils"
+```
+
+---
+
+## Success Metrics
+
+Track these over time:
+
+| Metric | Target | Current |
+|--------|--------|---------|
+| **Utils Coverage** | 100% | 100% ✅ |
+| **Integration Coverage** | >80% | 76% 🟡 |
+| **Avg Module Size** | <200 lines | ~180 ✅ |
+| **Test/Code Ratio** | >1.5 | 1.7 ✅ |
+
+---
+
+## References
+
+- **Example:** `packages/subagents/src/explorer/utils/` (99 tests, 100% coverage)
+- **Example:** `packages/core/src/indexer/utils/` (87 tests, 100% coverage)
+- **Style Guide:** [ARCHITECTURE.md](./ARCHITECTURE.md)
+- **Contributing:** [CONTRIBUTING.md](./CONTRIBUTING.md)
+
+---
+
+## Questions?
+
+- **"Should I extract this?"** → If you're asking, probably yes.
+- **"How small is too small?"** → <10 lines inline is OK.
+- **"100% coverage is too hard"** → Only for pure utilities. Integration can be 80%.
+- **"This feels like over-engineering"** → Testability = usability. If it's easy to test, it's easy to use.
+
+---
+
+**Remember:** Future you (and your teammates) will thank you for writing testable code! 🙏
+
diff --git a/package.json b/package.json
index 5ce1cf1..bd147b6 100644
--- a/package.json
+++ b/package.json
@@ -12,6 +12,7 @@
     "lint": "turbo lint",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "clean": "turbo clean && rm -rf node_modules",
     "format": "turbo format",
     "typecheck": "turbo typecheck",
diff --git a/packages/core/src/indexer/index.ts b/packages/core/src/indexer/index.ts
index ea72e0b..3230203 100644
--- a/packages/core/src/indexer/index.ts
+++ b/packages/core/src/indexer/index.ts
@@ -8,7 +8,7 @@ import * as path from 'node:path';
 import { scanRepository } from '../scanner';
 import type { Document } from '../scanner/types';
 import { VectorStorage } from '../vector';
-import type { EmbeddingDocument, SearchOptions, SearchResult } from '../vector/types';
+import type { SearchOptions, SearchResult } from '../vector/types';
 import type {
   FileMetadata,
   IndexError,
@@ -18,6 +18,7 @@ import type {
   IndexStats,
   UpdateOptions,
 } from './types';
+import { getExtensionForLanguage, prepareDocumentsForEmbedding } from './utils';
 
 const INDEXER_VERSION = '1.0.0';
 const DEFAULT_STATE_PATH = '.dev-agent/indexer-state.json';
@@ -83,7 +84,7 @@ export class RepositoryIndexer {
 
       const scanResult = await scanRepository({
         repoRoot: this.config.repositoryPath,
-        include: options.languages?.map((lang) => `**/*.${this.getExtensionForLanguage(lang)}`),
+        include: options.languages?.map((lang) => `**/*.${getExtensionForLanguage(lang)}`),
         exclude: [...this.config.excludePatterns, ...(options.excludePatterns || [])],
         languages: options.languages,
       });
@@ -100,7 +101,7 @@ export class RepositoryIndexer {
         percentComplete: 33,
       });
 
-      const embeddingDocuments = this.prepareDocumentsForEmbedding(scanResult.documents);
+      const embeddingDocuments = prepareDocumentsForEmbedding(scanResult.documents);
 
       // Phase 3: Batch embed and store
       onProgress?.({
@@ -231,7 +232,7 @@ export class RepositoryIndexer {
     }
 
     // Index new documents
-    const embeddingDocuments = this.prepareDocumentsForEmbedding(scanResult.documents);
+    const embeddingDocuments = prepareDocumentsForEmbedding(scanResult.documents);
     await this.vectorStorage.addDocuments(embeddingDocuments);
 
     // Update state
@@ -291,41 +292,6 @@ export class RepositoryIndexer {
   /**
    * Prepare scanner documents for embedding
    */
-  private prepareDocumentsForEmbedding(documents: Document[]): EmbeddingDocument[] {
-    return documents.map((doc) => ({
-      id: doc.id,
-      text: this.formatDocumentText(doc),
-      metadata: {
-        path: doc.metadata.file,
-        type: doc.type,
-        language: doc.language,
-        name: doc.metadata.name,
-        startLine: doc.metadata.startLine,
-        endLine: doc.metadata.endLine,
-        exported: doc.metadata.exported,
-        signature: doc.metadata.signature,
-        docstring: doc.metadata.docstring,
-      },
-    }));
-  }
-
-  /**
-   * Format document text for better embedding quality
-   */
-  private formatDocumentText(doc: Document): string {
-    // Combine name and content for better semantic understanding
-    const parts: string[] = [];
-
-    if (doc.metadata.name) {
-      parts.push(`${doc.type}: ${doc.metadata.name}`);
-    }
-
-    if (doc.text) {
-      parts.push(doc.text);
-    }
-
-    return parts.join('\n\n');
-  }
 
   /**
    * Load indexer state from disk
@@ -469,18 +435,6 @@ export class RepositoryIndexer {
   /**
    * Get file extension for a language
    */
-  private getExtensionForLanguage(language: string): string {
-    const extensions: Record<string, string> = {
-      typescript: 'ts',
-      javascript: 'js',
-      python: 'py',
-      go: 'go',
-      rust: 'rs',
-      markdown: 'md',
-    };
-
-    return extensions[language.toLowerCase()] || language;
-  }
 }
 
 export * from './types';
diff --git a/packages/core/src/indexer/utils/documents.test.ts b/packages/core/src/indexer/utils/documents.test.ts
new file mode 100644
index 0000000..fd4bf5c
--- /dev/null
+++ b/packages/core/src/indexer/utils/documents.test.ts
@@ -0,0 +1,297 @@
+/**
+ * Tests for document preparation utilities
+ */
+
+import { describe, expect, it } from 'vitest';
+import type { Document } from '../../scanner/types';
+import {
+  filterDocumentsByExport,
+  filterDocumentsByLanguage,
+  filterDocumentsByType,
+  prepareDocumentForEmbedding,
+  prepareDocumentsForEmbedding,
+} from './documents';
+
+describe('Document Preparation Utilities', () => {
+  const mockDocuments: Document[] = [
+    {
+      id: 'doc1',
+      type: 'function',
+      language: 'typescript',
+      text: 'function calculateTotal(items) { return items.reduce(...); }',
+      metadata: {
+        file: '/src/utils.ts',
+        name: 'calculateTotal',
+        startLine: 10,
+        endLine: 12,
+        exported: true,
+        signature: 'calculateTotal(items: Item[]): number',
+        docstring: 'Calculate total price from items',
+      },
+    },
+    {
+      id: 'doc2',
+      type: 'class',
+      language: 'typescript',
+      text: 'class User { constructor(name: string) {} }',
+      metadata: {
+        file: '/src/models.ts',
+        name: 'User',
+        startLine: 5,
+        endLine: 20,
+        exported: true,
+      },
+    },
+    {
+      id: 'doc3',
+      type: 'function',
+      language: 'javascript',
+      text: 'function helper() { return 42; }',
+      metadata: {
+        file: '/src/helper.js',
+        name: 'helper',
+        startLine: 1,
+        endLine: 3,
+        exported: false,
+      },
+    },
+  ];
+
+  describe('prepareDocumentsForEmbedding', () => {
+    it('should transform documents to embedding documents', () => {
+      const result = prepareDocumentsForEmbedding(mockDocuments);
+
+      expect(result).toHaveLength(3);
+      expect(result[0].id).toBe('doc1');
+      expect(result[0].text).toContain('function: calculateTotal');
+      expect(result[0].text).toContain('function calculateTotal');
+    });
+
+    it('should format document text properly', () => {
+      const result = prepareDocumentsForEmbedding([mockDocuments[0]]);
+
+      expect(result[0].text).toContain('function: calculateTotal');
+      expect(result[0].text).toContain('function calculateTotal(items)');
+    });
+
+    it('should transform metadata correctly', () => {
+      const result = prepareDocumentsForEmbedding([mockDocuments[0]]);
+      const metadata = result[0].metadata;
+
+      expect(metadata.path).toBe('/src/utils.ts');
+      expect(metadata.type).toBe('function');
+      expect(metadata.language).toBe('typescript');
+      expect(metadata.name).toBe('calculateTotal');
+      expect(metadata.startLine).toBe(10);
+      expect(metadata.endLine).toBe(12);
+      expect(metadata.exported).toBe(true);
+      expect(metadata.signature).toBe('calculateTotal(items: Item[]): number');
+      expect(metadata.docstring).toBe('Calculate total price from items');
+    });
+
+    it('should handle documents without optional metadata', () => {
+      const doc: Document = {
+        id: 'doc-minimal',
+        type: 'class',
+        language: 'typescript',
+        text: 'class Simple {}',
+        metadata: {
+          file: '/src/simple.ts',
+          name: 'Simple',
+          startLine: 1,
+          endLine: 1,
+          exported: false,
+        },
+      };
+
+      const result = prepareDocumentsForEmbedding([doc]);
+
+      expect(result[0].metadata.signature).toBeUndefined();
+      expect(result[0].metadata.docstring).toBeUndefined();
+    });
+
+    it('should handle empty array', () => {
+      const result = prepareDocumentsForEmbedding([]);
+      expect(result).toEqual([]);
+    });
+
+    it('should preserve document order', () => {
+      const result = prepareDocumentsForEmbedding(mockDocuments);
+
+      expect(result[0].id).toBe('doc1');
+      expect(result[1].id).toBe('doc2');
+      expect(result[2].id).toBe('doc3');
+    });
+  });
+
+  describe('prepareDocumentForEmbedding', () => {
+    it('should transform single document', () => {
+      const result = prepareDocumentForEmbedding(mockDocuments[0]);
+
+      expect(result.id).toBe('doc1');
+      expect(result.text).toContain('function: calculateTotal');
+      expect(result.metadata.path).toBe('/src/utils.ts');
+    });
+
+    it('should format text correctly', () => {
+      const result = prepareDocumentForEmbedding(mockDocuments[1]);
+
+      expect(result.text).toContain('class: User');
+      expect(result.text).toContain('class User');
+    });
+
+    it('should handle document without signature', () => {
+      const result = prepareDocumentForEmbedding(mockDocuments[2]);
+
+      expect(result.metadata.signature).toBeUndefined();
+    });
+  });
+
+  describe('filterDocumentsByExport', () => {
+    it('should filter exported documents', () => {
+      const result = filterDocumentsByExport(mockDocuments, true);
+
+      expect(result).toHaveLength(2);
+      expect(result.every((doc) => doc.metadata.exported)).toBe(true);
+    });
+
+    it('should filter non-exported documents', () => {
+      const result = filterDocumentsByExport(mockDocuments, false);
+
+      expect(result).toHaveLength(1);
+      expect(result[0].id).toBe('doc3');
+      expect(result[0].metadata.exported).toBe(false);
+    });
+
+    it('should handle empty array', () => {
+      const result = filterDocumentsByExport([], true);
+      expect(result).toEqual([]);
+    });
+
+    it('should return empty array when no matches', () => {
+      const allExported = mockDocuments.filter((doc) => doc.metadata.exported);
+      const result = filterDocumentsByExport(allExported, false);
+
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('filterDocumentsByType', () => {
+    it('should filter by single type', () => {
+      const result = filterDocumentsByType(mockDocuments, ['function']);
+
+      expect(result).toHaveLength(2);
+      expect(result.every((doc) => doc.type === 'function')).toBe(true);
+    });
+
+    it('should filter by multiple types', () => {
+      const result = filterDocumentsByType(mockDocuments, ['function', 'class']);
+
+      expect(result).toHaveLength(3);
+    });
+
+    it('should return empty array for non-matching types', () => {
+      const result = filterDocumentsByType(mockDocuments, ['interface', 'type']);
+
+      expect(result).toEqual([]);
+    });
+
+    it('should handle empty type array', () => {
+      const result = filterDocumentsByType(mockDocuments, []);
+
+      expect(result).toEqual([]);
+    });
+
+    it('should handle empty document array', () => {
+      const result = filterDocumentsByType([], ['function']);
+
+      expect(result).toEqual([]);
+    });
+
+    it('should be case-sensitive', () => {
+      const result = filterDocumentsByType(mockDocuments, ['Function']);
+
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('filterDocumentsByLanguage', () => {
+    it('should filter by single language', () => {
+      const result = filterDocumentsByLanguage(mockDocuments, ['typescript']);
+
+      expect(result).toHaveLength(2);
+      expect(result.every((doc) => doc.language === 'typescript')).toBe(true);
+    });
+
+    it('should filter by multiple languages', () => {
+      const result = filterDocumentsByLanguage(mockDocuments, ['typescript', 'javascript']);
+
+      expect(result).toHaveLength(3);
+    });
+
+    it('should be case-insensitive', () => {
+      const result = filterDocumentsByLanguage(mockDocuments, ['TypeScript', 'JavaScript']);
+
+      expect(result).toHaveLength(3);
+    });
+
+    it('should return empty array for non-matching languages', () => {
+      const result = filterDocumentsByLanguage(mockDocuments, ['python', 'go']);
+
+      expect(result).toEqual([]);
+    });
+
+    it('should handle empty language array', () => {
+      const result = filterDocumentsByLanguage(mockDocuments, []);
+
+      expect(result).toEqual([]);
+    });
+
+    it('should handle empty document array', () => {
+      const result = filterDocumentsByLanguage([], ['typescript']);
+
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('Integration scenarios', () => {
+    it('should filter and prepare documents', () => {
+      const exported = filterDocumentsByExport(mockDocuments, true);
+      const prepared = prepareDocumentsForEmbedding(exported);
+
+      expect(prepared).toHaveLength(2);
+      expect(prepared.every((doc) => doc.metadata.exported)).toBe(true);
+    });
+
+    it('should chain multiple filters', () => {
+      const typescript = filterDocumentsByLanguage(mockDocuments, ['typescript']);
+      const functions = filterDocumentsByType(typescript, ['function']);
+      const exported = filterDocumentsByExport(functions, true);
+
+      expect(exported).toHaveLength(1);
+      expect(exported[0].id).toBe('doc1');
+    });
+
+    it('should prepare filtered documents', () => {
+      const functions = filterDocumentsByType(mockDocuments, ['function']);
+      const prepared = prepareDocumentsForEmbedding(functions);
+
+      expect(prepared).toHaveLength(2);
+      expect(prepared.every((doc) => doc.metadata.type === 'function')).toBe(true);
+    });
+
+    it('should handle complex filtering pipeline', () => {
+      // Get public TypeScript functions
+      const typescript = filterDocumentsByLanguage(mockDocuments, ['typescript']);
+      const exported = filterDocumentsByExport(typescript, true);
+      const functions = filterDocumentsByType(exported, ['function']);
+      const prepared = prepareDocumentsForEmbedding(functions);
+
+      expect(prepared).toHaveLength(1);
+      expect(prepared[0].id).toBe('doc1');
+      expect(prepared[0].metadata.language).toBe('typescript');
+      expect(prepared[0].metadata.exported).toBe(true);
+      expect(prepared[0].metadata.type).toBe('function');
+    });
+  });
+});
diff --git a/packages/core/src/indexer/utils/documents.ts b/packages/core/src/indexer/utils/documents.ts
new file mode 100644
index 0000000..5b1e1a3
--- /dev/null
+++ b/packages/core/src/indexer/utils/documents.ts
@@ -0,0 +1,126 @@
+/**
+ * Document Preparation Utilities
+ * Functions for transforming documents for embedding generation
+ */
+
+import type { Document } from '../../scanner/types';
+import type { EmbeddingDocument } from '../../vector/types';
+import { formatDocumentText } from './formatting';
+
+/**
+ * Prepare documents for embedding generation
+ *
+ * Transforms Document objects from the scanner into EmbeddingDocument
+ * objects suitable for vector storage. Applies text formatting and
+ * metadata transformation.
+ *
+ * @param documents - Array of documents from repository scanner
+ * @returns Array of documents ready for embedding generation
+ *
+ * @example
+ * ```typescript
+ * const scanned = await scanRepository({ repoRoot: '/src' });
+ * const prepared = prepareDocumentsForEmbedding(scanned.documents);
+ *
+ * // Now ready for: await vectorStore.addDocuments(prepared)
+ * ```
+ */
+export function prepareDocumentsForEmbedding(documents: Document[]): EmbeddingDocument[] {
+  return documents.map((doc) => ({
+    id: doc.id,
+    text: formatDocumentText(doc),
+    metadata: {
+      path: doc.metadata.file,
+      type: doc.type,
+      language: doc.language,
+      name: doc.metadata.name,
+      startLine: doc.metadata.startLine,
+      endLine: doc.metadata.endLine,
+      exported: doc.metadata.exported,
+      signature: doc.metadata.signature,
+      docstring: doc.metadata.docstring,
+    },
+  }));
+}
+
+/**
+ * Prepare single document for embedding
+ *
+ * Convenience function for preparing a single document.
+ * Useful for incremental indexing or testing.
+ *
+ * @param doc - Document to prepare
+ * @returns Embedding document
+ *
+ * @example
+ * ```typescript
+ * const doc = { ... };
+ * const embeddingDoc = prepareDocumentForEmbedding(doc);
+ * ```
+ */
+export function prepareDocumentForEmbedding(doc: Document): EmbeddingDocument {
+  return {
+    id: doc.id,
+    text: formatDocumentText(doc),
+    metadata: {
+      path: doc.metadata.file,
+      type: doc.type,
+      language: doc.language,
+      name: doc.metadata.name,
+      startLine: doc.metadata.startLine,
+      endLine: doc.metadata.endLine,
+      exported: doc.metadata.exported,
+      signature: doc.metadata.signature,
+      docstring: doc.metadata.docstring,
+    },
+  };
+}
+
+/**
+ * Filter documents by export status
+ *
+ * @param documents - Documents to filter
+ * @param exported - True for exported only, false for non-exported only
+ * @returns Filtered documents
+ *
+ * @example
+ * ```typescript
+ * const publicAPI = filterDocumentsByExport(docs, true);
+ * ```
+ */
+export function filterDocumentsByExport(documents: Document[], exported: boolean): Document[] {
+  return documents.filter((doc) => doc.metadata.exported === exported);
+}
+
+/**
+ * Filter documents by type
+ *
+ * @param documents - Documents to filter
+ * @param types - Document types to include
+ * @returns Filtered documents
+ *
+ * @example
+ * ```typescript
+ * const functions = filterDocumentsByType(docs, ['function', 'method']);
+ * ```
+ */
+export function filterDocumentsByType(documents: Document[], types: string[]): Document[] {
+  return documents.filter((doc) => types.includes(doc.type));
+}
+
+/**
+ * Filter documents by language
+ *
+ * @param documents - Documents to filter
+ * @param languages - Languages to include
+ * @returns Filtered documents
+ *
+ * @example
+ * ```typescript
+ * const tsFiles = filterDocumentsByLanguage(docs, ['typescript', 'javascript']);
+ * ```
+ */
+export function filterDocumentsByLanguage(documents: Document[], languages: string[]): Document[] {
+  const lowerLanguages = languages.map((lang) => lang.toLowerCase());
+  return documents.filter((doc) => lowerLanguages.includes(doc.language.toLowerCase()));
+}
diff --git a/packages/core/src/indexer/utils/formatting.test.ts b/packages/core/src/indexer/utils/formatting.test.ts
new file mode 100644
index 0000000..3eed0a7
--- /dev/null
+++ b/packages/core/src/indexer/utils/formatting.test.ts
@@ -0,0 +1,344 @@
+/**
+ * Tests for formatting utilities
+ */
+
+import { describe, expect, it } from 'vitest';
+import type { Document } from '../../scanner/types';
+import {
+  cleanDocumentText,
+  formatDocumentText,
+  formatDocumentTextWithSignature,
+  truncateText,
+} from './formatting';
+
+describe('Formatting Utilities', () => {
+  describe('formatDocumentText', () => {
+    it('should format document with name and text', () => {
+      const doc: Document = {
+        id: 'doc1',
+        type: 'function',
+        language: 'typescript',
+        text: 'function calculateTotal(items) { return items.reduce(...); }',
+        metadata: {
+          file: '/src/utils.ts',
+          name: 'calculateTotal',
+          startLine: 10,
+          endLine: 12,
+          exported: false,
+        },
+      };
+
+      const result = formatDocumentText(doc);
+      expect(result).toBe(
+        'function: calculateTotal\n\nfunction calculateTotal(items) { return items.reduce(...); }'
+      );
+    });
+
+    it('should format document with only name (no text)', () => {
+      const doc: Document = {
+        id: 'doc2',
+        type: 'class',
+        language: 'typescript',
+        text: '',
+        metadata: {
+          file: '/src/models.ts',
+          name: 'User',
+          startLine: 5,
+          endLine: 20,
+          exported: false,
+        },
+      };
+
+      const result = formatDocumentText(doc);
+      expect(result).toBe('class: User');
+    });
+
+    it('should format document with only text (no name)', () => {
+      const doc: Document = {
+        id: 'doc3',
+        type: 'comment',
+        language: 'typescript',
+        text: '// This is a comment',
+        metadata: {
+          file: '/src/app.ts',
+          name: '',
+          startLine: 1,
+          endLine: 1,
+          exported: false,
+        },
+      };
+
+      const result = formatDocumentText(doc);
+      expect(result).toBe('// This is a comment');
+    });
+
+    it('should handle empty document', () => {
+      const doc: Document = {
+        id: 'doc4',
+        type: 'documentation',
+        language: 'typescript',
+        text: '',
+        metadata: {
+          file: '/src/empty.ts',
+          name: '',
+          startLine: 1,
+          endLine: 1,
+          exported: false,
+        },
+      };
+
+      const result = formatDocumentText(doc);
+      expect(result).toBe('');
+    });
+
+    it('should preserve multiline text', () => {
+      const doc: Document = {
+        id: 'doc5',
+        type: 'function',
+        language: 'typescript',
+        text: 'function foo() {\n  return 42;\n}',
+        metadata: {
+          file: '/src/utils.ts',
+          name: 'foo',
+          startLine: 1,
+          endLine: 3,
+          exported: false,
+        },
+      };
+
+      const result = formatDocumentText(doc);
+      expect(result).toContain('function: foo\n\nfunction foo()');
+      expect(result).toContain('return 42');
+    });
+  });
+
+  describe('formatDocumentTextWithSignature', () => {
+    it('should include signature when available', () => {
+      const doc: Document = {
+        id: 'doc1',
+        type: 'function',
+        language: 'typescript',
+        text: 'async function processData(data: string[]) { ... }',
+        metadata: {
+          file: '/src/processor.ts',
+          name: 'processData',
+          signature: 'processData(data: string[]): Promise<void>',
+          startLine: 10,
+          endLine: 15,
+          exported: false,
+        },
+      };
+
+      const result = formatDocumentTextWithSignature(doc);
+      expect(result).toContain('function: processData');
+      expect(result).toContain('processData(data: string[]): Promise<void>');
+      expect(result).toContain('async function processData');
+    });
+
+    it('should work without signature', () => {
+      const doc: Document = {
+        id: 'doc2',
+        type: 'class',
+        language: 'typescript',
+        text: 'class User { }',
+        metadata: {
+          file: '/src/models.ts',
+          name: 'User',
+          startLine: 1,
+          endLine: 1,
+          exported: false,
+        },
+      };
+
+      const result = formatDocumentTextWithSignature(doc);
+      expect(result).toBe('class: User\nclass User { }');
+    });
+
+    it('should handle empty signature', () => {
+      const doc: Document = {
+        id: 'doc3',
+        type: 'function',
+        language: 'typescript',
+        text: 'function test() { }',
+        metadata: {
+          file: '/src/test.ts',
+          name: 'test',
+          signature: '',
+          startLine: 1,
+          endLine: 1,
+          exported: false,
+        },
+      };
+
+      const result = formatDocumentTextWithSignature(doc);
+      expect(result).toBe('function: test\nfunction test() { }');
+    });
+  });
+
+  describe('truncateText', () => {
+    it('should not truncate text shorter than maxLength', () => {
+      const text = 'Short text';
+      expect(truncateText(text, 20)).toBe('Short text');
+    });
+
+    it('should not truncate text equal to maxLength', () => {
+      const text = 'Exactly 20 chars!!!.';
+      expect(truncateText(text, 20)).toBe('Exactly 20 chars!!!.');
+    });
+
+    it('should truncate long text and add ellipsis', () => {
+      const text = 'This is a very long text that needs to be truncated';
+      const result = truncateText(text, 20);
+
+      expect(result).toHaveLength(20);
+      expect(result.endsWith('...')).toBe(true);
+      expect(result).toBe('This is a very lo...');
+    });
+
+    it('should handle maxLength of 3 (minimum for ellipsis)', () => {
+      const text = 'Long text';
+      expect(truncateText(text, 3)).toBe('...');
+    });
+
+    it('should handle empty text', () => {
+      expect(truncateText('', 10)).toBe('');
+    });
+
+    it('should handle very small maxLength', () => {
+      const text = 'Test';
+      // Note: For very small maxLength (< 4), result may be longer than maxLength
+      // This is acceptable as "..." takes 3 chars minimum
+      const result = truncateText(text, 1);
+      expect(result).toBe('Te...');
+    });
+
+    it('should preserve exactly maxLength - 3 characters before ellipsis', () => {
+      const text = 'abcdefghijk';
+      const result = truncateText(text, 10);
+
+      expect(result).toBe('abcdefg...');
+      expect(result).toHaveLength(10);
+    });
+  });
+
+  describe('cleanDocumentText', () => {
+    it('should remove multiple spaces', () => {
+      const text = 'function  foo()    {  return  42; }';
+      expect(cleanDocumentText(text)).toBe('function foo() { return 42; }');
+    });
+
+    it('should reduce excessive newlines', () => {
+      const text = 'line1\n\n\n\nline2';
+      expect(cleanDocumentText(text)).toBe('line1\n\nline2');
+    });
+
+    it('should preserve single and double newlines', () => {
+      const text = 'line1\nline2\n\nline3';
+      expect(cleanDocumentText(text)).toBe('line1\nline2\n\nline3');
+    });
+
+    it('should trim leading and trailing whitespace', () => {
+      const text = '   text with spaces   ';
+      expect(cleanDocumentText(text)).toBe('text with spaces');
+    });
+
+    it('should handle combination of issues', () => {
+      const text = '  function  foo() {\n\n\n  return  42;\n}\n\n\n';
+      const expected = 'function foo() {\n\n return 42;\n}';
+      expect(cleanDocumentText(text)).toBe(expected);
+    });
+
+    it('should handle empty string', () => {
+      expect(cleanDocumentText('')).toBe('');
+    });
+
+    it('should handle text with only whitespace', () => {
+      expect(cleanDocumentText('   \n\n  ')).toBe('');
+    });
+
+    it('should handle text with tabs', () => {
+      const text = 'function\tfoo()\t{\treturn\t42; }';
+      // Tabs are preserved (not converted to spaces)
+      expect(cleanDocumentText(text)).toBe('function\tfoo()\t{\treturn\t42; }');
+    });
+
+    it('should handle already clean text', () => {
+      const text = 'Clean text\nWith proper spacing';
+      expect(cleanDocumentText(text)).toBe(text);
+    });
+  });
+
+  describe('Integration scenarios', () => {
+    it('should format and clean document text', () => {
+      const doc: Document = {
+        id: 'doc1',
+        type: 'function',
+        language: 'typescript',
+        text: 'function  foo() {\n\n\n  return  42;\n}',
+        metadata: {
+          file: '/src/utils.ts',
+          name: 'foo',
+          startLine: 1,
+          endLine: 3,
+        },
+      };
+
+      const formatted = formatDocumentText(doc);
+      const cleaned = cleanDocumentText(formatted);
+
+      expect(cleaned).toContain('function: foo');
+      expect(cleaned).not.toContain('  ');
+      expect(cleaned).not.toContain('\n\n\n');
+    });
+
+    it('should format, clean, and truncate', () => {
+      const doc: Document = {
+        id: 'doc1',
+        type: 'function',
+        language: 'typescript',
+        text: 'function calculateTotalWithVeryLongName() { return items.reduce((sum, item) => sum + item.price, 0); }',
+        metadata: {
+          file: '/src/utils.ts',
+          name: 'calculateTotalWithVeryLongName',
+          startLine: 1,
+          endLine: 1,
+          exported: false,
+        },
+      };
+
+      const formatted = formatDocumentText(doc);
+      const cleaned = cleanDocumentText(formatted);
+      const truncated = truncateText(cleaned, 50);
+
+      expect(truncated).toHaveLength(50);
+      expect(truncated.endsWith('...')).toBe(true);
+    });
+
+    it('should handle complex formatting pipeline', () => {
+      const doc: Document = {
+        id: 'doc1',
+        type: 'class',
+        language: 'typescript',
+        text: 'class   User  {\n\n\n  constructor(name:  string) {}\n\n\n}',
+        metadata: {
+          file: '/src/models.ts',
+          name: 'User',
+          signature: 'class User',
+          startLine: 1,
+          endLine: 5,
+          exported: false,
+        },
+      };
+
+      // Full pipeline
+      const withSig = formatDocumentTextWithSignature(doc);
+      const cleaned = cleanDocumentText(withSig);
+
+      expect(cleaned).toContain('class: User');
+      expect(cleaned).toContain('class User');
+      expect(cleaned).toContain('constructor(name: string)');
+      expect(cleaned).not.toContain('   ');
+      expect(cleaned).not.toContain('\n\n\n');
+    });
+  });
+});
diff --git a/packages/core/src/indexer/utils/formatting.ts b/packages/core/src/indexer/utils/formatting.ts
new file mode 100644
index 0000000..61d7534
--- /dev/null
+++ b/packages/core/src/indexer/utils/formatting.ts
@@ -0,0 +1,143 @@
+/**
+ * Formatting Utilities
+ * Functions for document text formatting and optimization
+ */
+
+import type { Document } from '../../scanner/types';
+
+/**
+ * Format document text for better embedding quality
+ *
+ * Combines document name and content to provide rich semantic context
+ * for embedding generation. This improves search relevance by including
+ * both structural information (type, name) and actual content.
+ *
+ * @param doc - Document to format
+ * @returns Formatted text suitable for embedding
+ *
+ * @example
+ * ```typescript
+ * const doc = {
+ *   type: 'function',
+ *   metadata: { name: 'calculateTotal' },
+ *   text: 'function calculateTotal(items) { ... }'
+ * };
+ *
+ * formatDocumentText(doc);
+ * // "function: calculateTotal\n\nfunction calculateTotal(items) { ... }"
+ * ```
+ */
+export function formatDocumentText(doc: Document): string {
+  const parts: string[] = [];
+
+  // Add type and name for context
+  if (doc.metadata.name) {
+    parts.push(`${doc.type}: ${doc.metadata.name}`);
+  }
+
+  // Add actual content
+  if (doc.text) {
+    parts.push(doc.text);
+  }
+
+  return parts.join('\n\n');
+}
+
+/**
+ * Format document text with signature
+ *
+ * Includes function/method signature for enhanced searchability.
+ * Useful when you want to make signatures more prominent in search.
+ *
+ * @param doc - Document to format
+ * @returns Formatted text with signature emphasis
+ *
+ * @example
+ * ```typescript
+ * const doc = {
+ *   type: 'function',
+ *   metadata: {
+ *     name: 'processData',
+ *     signature: 'processData(data: string[]): Promise<void>'
+ *   },
+ *   text: 'async function processData...'
+ * };
+ *
+ * formatDocumentTextWithSignature(doc);
+ * // "function: processData\nprocessData(data: string[])...
+ * ```
+ */
+export function formatDocumentTextWithSignature(doc: Document): string {
+  const parts: string[] = [];
+
+  // Add type and name
+  if (doc.metadata.name) {
+    parts.push(`${doc.type}: ${doc.metadata.name}`);
+  }
+
+  // Add signature if available
+  if (doc.metadata.signature) {
+    parts.push(doc.metadata.signature);
+  }
+
+  // Add content
+  if (doc.text) {
+    parts.push(doc.text);
+  }
+
+  return parts.join('\n');
+}
+
+/**
+ * Truncate document text to maximum length
+ *
+ * Useful for limiting embedding input size while preserving
+ * the most important information (beginning of the document).
+ *
+ * @param text - Text to truncate
+ * @param maxLength - Maximum length in characters
+ * @returns Truncated text with ellipsis if needed
+ *
+ * @example
+ * ```typescript
+ * truncateText('Long text...', 20);
+ * // "Long text...
+ *
+ * truncateText('Short', 20);
+ * // "Short"
+ * ```
+ */
+export function truncateText(text: string, maxLength: number): string {
+  if (text.length <= maxLength) {
+    return text;
+  }
+
+  return `${text.slice(0, maxLength - 3)}...`;
+}
+
+/**
+ * Clean document text by removing excessive whitespace
+ *
+ * Normalizes whitespace while preserving intentional line breaks.
+ * Helps reduce token count for embeddings.
+ *
+ * @param text - Text to clean
+ * @returns Cleaned text
+ *
+ * @example
+ * ```typescript
+ * cleanDocumentText('function  foo() {\n\n\n  return  42;\n}');
+ * // "function foo() {\n\n  return 42;\n}"
+ * ```
+ */
+export function cleanDocumentText(text: string): string {
+  return (
+    text
+      // Replace multiple spaces with single space
+      .replace(/ +/g, ' ')
+      // Replace more than 2 newlines with 2 newlines
+      .replace(/\n{3,}/g, '\n\n')
+      // Trim leading/trailing whitespace
+      .trim()
+  );
+}
diff --git a/packages/core/src/indexer/utils/index.ts b/packages/core/src/indexer/utils/index.ts
new file mode 100644
index 0000000..ca3c5d0
--- /dev/null
+++ b/packages/core/src/indexer/utils/index.ts
@@ -0,0 +1,32 @@
+/**
+ * Indexer Utilities
+ *
+ * Modular utilities for repository indexing organized by domain.
+ *
+ * @module indexer/utils
+ */
+
+// Document preparation
+export {
+  filterDocumentsByExport,
+  filterDocumentsByLanguage,
+  filterDocumentsByType,
+  prepareDocumentForEmbedding,
+  prepareDocumentsForEmbedding,
+} from './documents';
+
+// Text formatting
+export {
+  cleanDocumentText,
+  formatDocumentText,
+  formatDocumentTextWithSignature,
+  truncateText,
+} from './formatting';
+
+// Language mapping
+export {
+  getExtensionForLanguage,
+  getLanguageFromExtension,
+  getSupportedLanguages,
+  isLanguageSupported,
+} from './language';
diff --git a/packages/core/src/indexer/utils/language.test.ts b/packages/core/src/indexer/utils/language.test.ts
new file mode 100644
index 0000000..a1956e1
--- /dev/null
+++ b/packages/core/src/indexer/utils/language.test.ts
@@ -0,0 +1,201 @@
+/**
+ * Tests for language utilities
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  getExtensionForLanguage,
+  getLanguageFromExtension,
+  getSupportedLanguages,
+  isLanguageSupported,
+} from './language';
+
+describe('Language Utilities', () => {
+  describe('getExtensionForLanguage', () => {
+    it('should return correct extension for TypeScript', () => {
+      expect(getExtensionForLanguage('typescript')).toBe('ts');
+    });
+
+    it('should return correct extension for JavaScript', () => {
+      expect(getExtensionForLanguage('javascript')).toBe('js');
+    });
+
+    it('should return correct extension for Python', () => {
+      expect(getExtensionForLanguage('python')).toBe('py');
+    });
+
+    it('should return correct extension for Go', () => {
+      expect(getExtensionForLanguage('go')).toBe('go');
+    });
+
+    it('should return correct extension for Rust', () => {
+      expect(getExtensionForLanguage('rust')).toBe('rs');
+    });
+
+    it('should return correct extension for Markdown', () => {
+      expect(getExtensionForLanguage('markdown')).toBe('md');
+    });
+
+    it('should be case-insensitive', () => {
+      expect(getExtensionForLanguage('TypeScript')).toBe('ts');
+      expect(getExtensionForLanguage('PYTHON')).toBe('py');
+      expect(getExtensionForLanguage('JavaScript')).toBe('js');
+    });
+
+    it('should return the language itself for unknown languages', () => {
+      expect(getExtensionForLanguage('cobol')).toBe('cobol');
+      expect(getExtensionForLanguage('fortran')).toBe('fortran');
+    });
+
+    it('should handle empty string', () => {
+      expect(getExtensionForLanguage('')).toBe('');
+    });
+
+    it('should handle mixed case unknown languages', () => {
+      expect(getExtensionForLanguage('UnknownLang')).toBe('UnknownLang');
+    });
+  });
+
+  describe('getSupportedLanguages', () => {
+    it('should return array of supported languages', () => {
+      const languages = getSupportedLanguages();
+      expect(Array.isArray(languages)).toBe(true);
+      expect(languages.length).toBeGreaterThan(0);
+    });
+
+    it('should include common languages', () => {
+      const languages = getSupportedLanguages();
+      expect(languages).toContain('typescript');
+      expect(languages).toContain('javascript');
+      expect(languages).toContain('python');
+      expect(languages).toContain('go');
+      expect(languages).toContain('rust');
+      expect(languages).toContain('markdown');
+    });
+
+    it('should return consistent results', () => {
+      const languages1 = getSupportedLanguages();
+      const languages2 = getSupportedLanguages();
+      expect(languages1).toEqual(languages2);
+    });
+
+    it('should return exactly 6 supported languages', () => {
+      expect(getSupportedLanguages()).toHaveLength(6);
+    });
+  });
+
+  describe('isLanguageSupported', () => {
+    it('should return true for supported languages', () => {
+      expect(isLanguageSupported('typescript')).toBe(true);
+      expect(isLanguageSupported('javascript')).toBe(true);
+      expect(isLanguageSupported('python')).toBe(true);
+      expect(isLanguageSupported('go')).toBe(true);
+      expect(isLanguageSupported('rust')).toBe(true);
+      expect(isLanguageSupported('markdown')).toBe(true);
+    });
+
+    it('should return false for unsupported languages', () => {
+      expect(isLanguageSupported('cobol')).toBe(false);
+      expect(isLanguageSupported('fortran')).toBe(false);
+      expect(isLanguageSupported('unknown')).toBe(false);
+    });
+
+    it('should be case-insensitive', () => {
+      expect(isLanguageSupported('TypeScript')).toBe(true);
+      expect(isLanguageSupported('PYTHON')).toBe(true);
+      expect(isLanguageSupported('JavaScript')).toBe(true);
+    });
+
+    it('should return false for empty string', () => {
+      expect(isLanguageSupported('')).toBe(false);
+    });
+
+    it('should handle special characters', () => {
+      expect(isLanguageSupported('type-script')).toBe(false);
+      expect(isLanguageSupported('java script')).toBe(false);
+    });
+  });
+
+  describe('getLanguageFromExtension', () => {
+    it('should return correct language for TypeScript extensions', () => {
+      expect(getLanguageFromExtension('.ts')).toBe('typescript');
+      expect(getLanguageFromExtension('ts')).toBe('typescript');
+    });
+
+    it('should return correct language for JavaScript extensions', () => {
+      expect(getLanguageFromExtension('.js')).toBe('javascript');
+      expect(getLanguageFromExtension('js')).toBe('javascript');
+    });
+
+    it('should return correct language for Python extensions', () => {
+      expect(getLanguageFromExtension('.py')).toBe('python');
+      expect(getLanguageFromExtension('py')).toBe('python');
+    });
+
+    it('should return correct language for Go extensions', () => {
+      expect(getLanguageFromExtension('.go')).toBe('go');
+      expect(getLanguageFromExtension('go')).toBe('go');
+    });
+
+    it('should return correct language for Rust extensions', () => {
+      expect(getLanguageFromExtension('.rs')).toBe('rust');
+      expect(getLanguageFromExtension('rs')).toBe('rust');
+    });
+
+    it('should return correct language for Markdown extensions', () => {
+      expect(getLanguageFromExtension('.md')).toBe('markdown');
+      expect(getLanguageFromExtension('md')).toBe('markdown');
+    });
+
+    it('should return null for unknown extensions', () => {
+      expect(getLanguageFromExtension('.xyz')).toBeNull();
+      expect(getLanguageFromExtension('unknown')).toBeNull();
+    });
+
+    it('should return null for empty string', () => {
+      expect(getLanguageFromExtension('')).toBeNull();
+    });
+
+    it('should handle extensions with multiple dots', () => {
+      expect(getLanguageFromExtension('.test.ts')).toBeNull();
+    });
+  });
+
+  describe('Integration scenarios', () => {
+    it('should round-trip language to extension and back', () => {
+      const languages = getSupportedLanguages();
+
+      for (const language of languages) {
+        const ext = getExtensionForLanguage(language);
+        const roundTrip = getLanguageFromExtension(ext);
+        expect(roundTrip).toBe(language);
+      }
+    });
+
+    it('should filter supported languages from a list', () => {
+      const allLanguages = ['typescript', 'cobol', 'python', 'fortran', 'rust'];
+      const supported = allLanguages.filter((lang) => isLanguageSupported(lang));
+
+      expect(supported).toEqual(['typescript', 'python', 'rust']);
+    });
+
+    it('should map file paths to languages', () => {
+      const files = ['app.ts', 'script.py', 'main.go', 'lib.rs', 'README.md', 'data.csv'];
+
+      const languageMap = files.map((file) => {
+        const ext = file.split('.').pop() || '';
+        return {
+          file,
+          language: getLanguageFromExtension(ext),
+        };
+      });
+
+      expect(languageMap[0].language).toBe('typescript');
+      expect(languageMap[1].language).toBe('python');
+      expect(languageMap[2].language).toBe('go');
+      expect(languageMap[3].language).toBe('rust');
+      expect(languageMap[4].language).toBe('markdown');
+      expect(languageMap[5].language).toBeNull();
+    });
+  });
+});
diff --git a/packages/core/src/indexer/utils/language.ts b/packages/core/src/indexer/utils/language.ts
new file mode 100644
index 0000000..940473c
--- /dev/null
+++ b/packages/core/src/indexer/utils/language.ts
@@ -0,0 +1,83 @@
+/**
+ * Language Utilities
+ * Functions for language and file extension mapping
+ */
+
+/**
+ * Language to file extension mapping
+ */
+const LANGUAGE_EXTENSIONS: Record<string, string> = {
+  typescript: 'ts',
+  javascript: 'js',
+  python: 'py',
+  go: 'go',
+  rust: 'rs',
+  markdown: 'md',
+};
+
+/**
+ * Get file extension for a given language
+ *
+ * @param language - Programming language name
+ * @returns File extension (without dot)
+ *
+ * @example
+ * ```typescript
+ * getExtensionForLanguage('typescript'); // 'ts'
+ * getExtensionForLanguage('python');     // 'py'
+ * getExtensionForLanguage('unknown');    // 'unknown'
+ * ```
+ */
+export function getExtensionForLanguage(language: string): string {
+  return LANGUAGE_EXTENSIONS[language.toLowerCase()] || language;
+}
+
+/**
+ * Get supported languages
+ *
+ * @returns Array of supported language names
+ *
+ * @example
+ * ```typescript
+ * const languages = getSupportedLanguages();
+ * // ['typescript', 'javascript', 'python', 'go', 'rust', 'markdown']
+ * ```
+ */
+export function getSupportedLanguages(): string[] {
+  return Object.keys(LANGUAGE_EXTENSIONS);
+}
+
+/**
+ * Check if a language is supported
+ *
+ * @param language - Programming language name
+ * @returns True if language is supported
+ *
+ * @example
+ * ```typescript
+ * isLanguageSupported('typescript'); // true
+ * isLanguageSupported('cobol');      // false
+ * ```
+ */
+export function isLanguageSupported(language: string): boolean {
+  return language.toLowerCase() in LANGUAGE_EXTENSIONS;
+}
+
+/**
+ * Get language from file extension
+ *
+ * @param extension - File extension (with or without dot)
+ * @returns Language name or null if not found
+ *
+ * @example
+ * ```typescript
+ * getLanguageFromExtension('.ts');  // 'typescript'
+ * getLanguageFromExtension('py');   // 'python'
+ * getLanguageFromExtension('.xyz'); // null
+ * ```
+ */
+export function getLanguageFromExtension(extension: string): string | null {
+  const ext = extension.startsWith('.') ? extension.slice(1) : extension;
+  const entry = Object.entries(LANGUAGE_EXTENSIONS).find(([, value]) => value === ext);
+  return entry ? entry[0] : null;
+}