Add comprehensive tests for vector/semantic search functionality

- Implement full coverage tests for Embedder model loading and embedding generation
- Add CRUD operations and caching tests for VectorStore
- Include cosine similarity computation tests
- Validate semantic search accuracy and relevance through various queries
- Establish performance benchmarks for embedding and search operations
- Ensure edge cases and error handling are covered
- Test thread safety and concurrent access scenarios
- Verify availability of semantic search dependencies

.claude/rules/active_memory.md

@@ -0,0 +1,13 @@
+# Active Memory
+
+> Auto-generated understanding of frequently accessed files using GEMINI.
+> Last updated: 2025-12-14T08:59:41.526Z
+> Files analyzed: 10
+> CLI Tool: gemini
+
+---
+
+[object Object]
+
+---
+

.claude/rules/active_memory_config.json

@@ -0,0 +1,4 @@
+{
+  "interval": "manual",
+  "tool": "gemini"
+}

.claude/rules/cli-tools-usage.md

@@ -0,0 +1,36 @@
+# CLI Tools Usage Rules
+
+## Tool Selection
+
+### Gemini & Qwen
+**Use for**: Analysis, documentation, code exploration, architecture review
+- Default MODE: `analysis` (read-only)
+- Prefer Gemini; use Qwen as fallback
+- Large context window, pattern recognition
+
+### Codex
+**Use for**: Feature implementation, bug fixes, autonomous development
+- Requires explicit `--mode auto` or `--mode write`
+- Best for: Implementation, testing, automation
+
+## Core Principles
+
+- Use tools early and often - tools are faster and more thorough
+- Always use `ccw cli exec` for consistent parameter handling
+- ALWAYS reference exactly ONE template in RULES section
+- Require EXPLICIT `--mode write` or `--mode auto` for modifications
+- NEVER use escape characters (`\$`, `\"`, `\'`) in CLI commands
+
+## Permission Framework
+
+- `analysis` (default): Read-only, safe for auto-execution
+- `write`: Requires explicit `--mode write` - creates/modifies/deletes files
+- `auto`: Requires explicit `--mode auto` - full autonomous operations (Codex only)
+
+## Timeout Guidelines
+
+- Simple (5-10min): Analysis, search
+- Medium (10-20min): Refactoring, documentation
+- Complex (20-60min): Implementation, migration
+- Heavy (60-120min): Large codebase, multi-file operations
+- Codex multiplier: 3x allocated time (minimum 15min)

.claude/rules/coding-philosophy.md

@@ -1,19 +1,6 @@
+# Coding Philosophy
 
-### Tool Context Protocols
-For all  tool usage, command syntax, and integration guidelines:
-- **Tool Strategy**: @~/.claude/workflows/tool-strategy.md
-- **Intelligent Context Strategy**: @~/.claude/workflows/intelligent-tools-strategy.md
-- **Context Search Commands**: @~/.claude/workflows/context-search-strategy.md
-
-**Context Requirements**:
-- Identify 3+ existing similar patterns before implementation
-- Map dependencies and integration points
-- Understand testing framework and coding conventions
-
-
-## Philosophy
-
-### Core Beliefs
+## Core Beliefs
 
 - **Pursue good taste** - Eliminate edge cases to make code logic natural and elegant
 - **Embrace extreme simplicity** - Complexity is the root of all evil
@@ -27,33 +14,16 @@ For all  tool usage, command syntax, and integration guidelines:
 - **Minimize changes** - Only modify what's directly required; avoid refactoring, adding features, or "improving" code beyond the request
 - **No unsolicited documentation** - NEVER generate reports, documentation files, or summaries without explicit user request. If required, save to .workflow/.scratchpad/
 
-### Simplicity Means
+## Simplicity Means
 
 - Single responsibility per function/class
 - Avoid premature abstractions
 - No clever tricks - choose the boring solution
 - If you need to explain it, it's too complex
 
-## Project Integration
+## Fix, Don't Hide
 
-### Learning the Codebase
-
-- Find 3 similar features/components
-- Identify common patterns and conventions
-- Use same libraries/utilities when possible
-- Follow existing test patterns
-
-### Tooling
-
-- Use project's existing build system
-- Use project's test framework  
-- Use project's formatter/linter settings
-- Don't introduce new tools without strong justification
-
-
-### Fix, Don't Hide
-
-- **Solve problems, don't silence symptoms** - Skipped tests, `@ts-ignore`, empty catch, `as any`, excessive timeouts = hiding bugs, not fixing them
+**Solve problems, don't silence symptoms** - Skipped tests, `@ts-ignore`, empty catch, `as any`, excessive timeouts = hiding bugs, not fixing them
 
 **NEVER**:
 - Make assumptions - verify with existing code
@@ -70,18 +40,3 @@ For all  tool usage, command syntax, and integration guidelines:
 - Learn from existing implementations
 - Stop after 3 failed attempts and reassess
 - **Edit fallback**: When Edit tool fails 2+ times on same file, try Bash sed/awk first, then Write to recreate if still failing
-
-## Platform-Specific Guidelines
-
-### Windows Path Format Guidelines
-- **MCP Tools**: Double backslash `D:\\path\\file.txt`
-- **Bash Commands**: Forward slash `D:/path/file.txt` or `/d/path/file.txt`
-- **Relative Paths**: Universal (works in both)
-
-#### **Content Uniqueness Rules**
-
-- **Each layer owns its abstraction level** - no content sharing between layers
-- **Reference, don't duplicate** - point to other layers, never copy content
-- **Maintain perspective** - each layer sees the system at its appropriate scale
-- **Avoid implementation creep** - higher layers stay architectural
-

.claude/rules/context-requirements.md

@@ -0,0 +1,7 @@
+# Context Requirements
+
+Before implementation, always:
+
+- Identify 3+ existing similar patterns before implementation
+- Map dependencies and integration points
+- Understand testing framework and coding conventions

.claude/rules/intelligent-tools-strategy.md

@@ -15,14 +15,25 @@
 ### Universal Prompt Template
 
 ```
-PURPOSE: [objective + why + success criteria]
-TASK: • [step 1] • [step 2] • [step 3]
+PURPOSE: [what] + [why] + [success criteria] + [constraints/scope]
+TASK: • [step 1: specific action] • [step 2: specific action] • [step 3: specific action]
 MODE: [analysis|write|auto]
-CONTEXT: @**/* | Memory: [session/tech/module context]
-EXPECTED: [format + quality + structure]
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints] | MODE=[permission]
+CONTEXT: @[file patterns] | Memory: [session/tech/module context]
+EXPECTED: [deliverable format] + [quality criteria] + [structure requirements]
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [domain constraints] | MODE=[permission]
 ```
 
+### Intent Capture Checklist (Before CLI Execution)
+
+**⚠️ CRITICAL**: Before executing any CLI command, verify these intent dimensions:
+**Intent Validation Questions**:
+- [ ] Is the objective specific and measurable?
+- [ ] Are success criteria defined?
+- [ ] Is the scope clearly bounded?
+- [ ] Are constraints and limitations stated?
+- [ ] Is the expected output format clear?
+- [ ] Is the action level (read/write) explicit?
+
 ### Tool Selection
 
 | Task Type | Tool | Fallback |
@@ -128,14 +139,15 @@ ASSISTANT RESPONSE: [Previous output]
 
 Every command MUST include these fields:
 
-| Field | Purpose | Example |
-|-------|---------|---------|
-| **PURPOSE** | Goal, why needed, success criteria | "Analyze auth module for security vulnerabilities" |
-| **TASK** | Actionable steps (• bullet format) | "• Review patterns • Identify risks • Document findings" |
-| **MODE** | Permission level | `analysis` / `write` / `auto` |
-| **CONTEXT** | File patterns + Memory context | `@src/**/* | Memory: Previous refactoring (abc123)` |
-| **EXPECTED** | Deliverable format, quality criteria | "Security report with risk levels and recommendations" |
-| **RULES** | **Template (REQUIRED)** + constraints | `$(cat ~/.claude/.../analysis/02-analyze-code-patterns.txt) | Focus on auth | analysis=READ-ONLY` |
+| Field | Purpose | Components | Bad Example | Good Example |
+|-------|---------|------------|-------------|--------------|
+| **PURPOSE** | Goal + motivation + success | What + Why + Success Criteria + Constraints | "Analyze code" | "Identify security vulnerabilities in auth module to pass compliance audit; success = all OWASP Top 10 addressed; scope = src/auth/** only" |
+| **TASK** | Actionable steps | Specific verbs + targets | "• Review code • Find issues" | "• Scan for SQL injection in query builders • Check XSS in template rendering • Verify CSRF token validation" |
+| **MODE** | Permission level | analysis / write / auto | (missing) | "analysis" or "write" |
+| **CONTEXT** | File scope + history | File patterns + Memory | "@**/*" | "@src/auth/**/*.ts @shared/utils/security.ts \| Memory: Previous auth refactoring (WFS-001)" |
+| **EXPECTED** | Output specification | Format + Quality + Structure | "Report" | "Markdown report with: severity levels (Critical/High/Medium/Low), file:line references, remediation code snippets, priority ranking" |
+| **RULES** | Template + constraints | $(cat template) + domain rules | (missing) | "$(cat ~/.claude/.../security.txt) \| Focus on authentication \| Ignore test files \| analysis=READ-ONLY" |
+
 
 ### CONTEXT Configuration
 
@@ -303,42 +315,55 @@ CCW automatically maps to tool-specific syntax:
 
 ### Command Examples
 
+#### Task-Type Specific Templates
+
+**Analysis Task** (Security Audit):
 ```bash
-# Analysis (default)
 ccw cli exec "
-PURPOSE: Analyze authentication
-TASK: • Review patterns • Identify risks
+PURPOSE: Identify OWASP Top 10 vulnerabilities in authentication module to pass security audit; success = all critical/high issues documented with remediation
+TASK: • Scan for injection flaws (SQL, command, LDAP) • Check authentication bypass vectors • Evaluate session management • Assess sensitive data exposure
 MODE: analysis
-CONTEXT: @**/* @../shared/**/*
-EXPECTED: Analysis report
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | analysis=READ-ONLY
-" --tool gemini --cd src/auth --includeDirs ../shared
-
-# Write mode
-ccw cli exec "
-PURPOSE: Generate API docs
-TASK: • Create docs • Add examples
-MODE: write
-CONTEXT: @src/api/**/*
-EXPECTED: Complete documentation
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | write=CREATE/MODIFY/DELETE
-" --tool gemini --mode write
-
-# Auto mode (Codex)
-ccw cli exec "
-PURPOSE: Implement auth module
-TASK: • Create service • Add validation • Setup JWT
-MODE: auto
-CONTEXT: @**/* | Memory: Following project security patterns
-EXPECTED: Complete module with tests
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | auto=FULL
-" --tool codex --mode auto
-
-# Fallback strategy
-ccw cli exec "<prompt>" --tool gemini    # Primary
-ccw cli exec "<prompt>" --tool qwen      # Fallback
+CONTEXT: @src/auth/**/* @src/middleware/auth.ts | Memory: Using bcrypt for passwords, JWT for sessions
+EXPECTED: Security report with: severity matrix, file:line references, CVE mappings where applicable, remediation code snippets prioritized by risk
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/03-assess-security-risks.txt) | Focus on authentication | Ignore test files | analysis=READ-ONLY
+" --tool gemini --cd src/auth --timeout 600000
 ```
 
+**Implementation Task** (New Feature):
+```bash
+ccw cli exec "
+PURPOSE: Implement rate limiting for API endpoints to prevent abuse; must be configurable per-endpoint; backward compatible with existing clients
+TASK: • Create rate limiter middleware with sliding window • Implement per-route configuration • Add Redis backend for distributed state • Include bypass for internal services
+MODE: auto
+CONTEXT: @src/middleware/**/* @src/config/**/* | Memory: Using Express.js, Redis already configured, existing middleware pattern in auth.ts
+EXPECTED: Production-ready code with: TypeScript types, unit tests, integration test, configuration example, migration guide
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow existing middleware patterns | No breaking changes | auto=FULL
+" --tool codex --mode auto --timeout 1800000
+```
+
+**Bug Fix Task**:
+```bash
+ccw cli exec "
+PURPOSE: Fix memory leak in WebSocket connection handler causing server OOM after 24h; root cause must be identified before any fix
+TASK: • Trace connection lifecycle from open to close • Identify event listener accumulation • Check cleanup on disconnect • Verify garbage collection eligibility
+MODE: analysis
+CONTEXT: @src/websocket/**/* @src/services/connection-manager.ts | Memory: Using ws library, ~5000 concurrent connections in production
+EXPECTED: Root cause analysis with: memory profile, leak source (file:line), fix recommendation with code, verification steps
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt) | Focus on resource cleanup | analysis=READ-ONLY
+" --tool gemini --cd src --timeout 900000
+```
+
+**Refactoring Task**:
+```bash
+ccw cli exec "
+PURPOSE: Refactor payment processing to use strategy pattern for multi-gateway support; no functional changes; all existing tests must pass
+TASK: • Extract gateway interface from current implementation • Create strategy classes for Stripe, PayPal • Implement factory for gateway selection • Migrate existing code to use strategies
+MODE: write
+CONTEXT: @src/payments/**/* @src/types/payment.ts | Memory: Currently only Stripe, adding PayPal next sprint, must support future gateways
+EXPECTED: Refactored code with: strategy interface, concrete implementations, factory class, updated tests, migration checklist
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-refactor-codebase.txt) | Preserve all existing behavior | Tests must pass | write=CREATE/MODIFY/DELETE
+" --tool gemini --mode write --timeout 1200000
+```
 ---
 
 ## Configuration

.claude/rules/project-integration.md

@@ -0,0 +1,22 @@
+# Project Integration Rules
+
+## Learning the Codebase
+
+- Find 3 similar features/components
+- Identify common patterns and conventions
+- Use same libraries/utilities when possible
+- Follow existing test patterns
+
+## Tooling
+
+- Use project's existing build system
+- Use project's test framework
+- Use project's formatter/linter settings
+- Don't introduce new tools without strong justification
+
+## Content Uniqueness Rules
+
+- **Each layer owns its abstraction level** - no content sharing between layers
+- **Reference, don't duplicate** - point to other layers, never copy content
+- **Maintain perspective** - each layer sees the system at its appropriate scale
+- **Avoid implementation creep** - higher layers stay architectural

.claude/rules/tool-selection.md

@@ -0,0 +1,88 @@
+# Tool Selection Rules
+
+## Context Gathering
+
+### Use Exa
+- Researching external APIs, libraries, frameworks
+- Need recent documentation beyond knowledge cutoff
+- Looking for implementation examples in public repos
+- User mentions specific library/framework names
+- Questions about "best practices" or "how does X work"
+
+### Use read_file (MCP)
+- Reading multiple related files at once
+- Directory traversal with pattern matching
+- Searching file content with regex
+- Need to limit depth/file count for large directories
+- Batch operations on multiple files
+- Pattern-based filtering (glob + content regex)
+
+### Use codex_lens
+- Large codebase (>500 files) requiring repeated searches
+- Need semantic understanding of code relationships
+- Working across multiple sessions
+- Symbol-level navigation needed
+- Finding all implementations of interface/class
+- Tracking function calls across codebase
+
+### Use smart_search
+- Unknown file locations
+- Concept/semantic search ("authentication logic", "payment processing")
+- Medium-sized codebase (100-500 files)
+- One-time or infrequent searches
+- Natural language queries about code structure
+
+**Mode Selection**:
+- `auto`: Let tool decide (default)
+- `exact`: Known exact pattern
+- `fuzzy`: Typo-tolerant search
+- `semantic`: Concept-based search
+- `graph`: Dependency analysis
+
+## File Modification
+
+### Use edit_file (MCP)
+- Built-in Edit tool failed 1+ times
+- Need dry-run preview before applying changes
+- Need line-based operations (insert_after, insert_before)
+- Need to replace all occurrences at once
+- Built-in Edit returns "old_string not found"
+- Whitespace/formatting issues in built-in Edit
+
+**Mode Selection**:
+- `mode=update`: Replace text
+- `mode=line`: Line-based operations
+
+### Use write_file (MCP)
+- Creating brand new files
+- MCP edit_file still fails (last resort)
+- Need to completely replace file content
+- Need backup before overwriting
+- User explicitly asks to "recreate file"
+
+## Priority Logic
+
+**File Reading**:
+1. Known single file → Built-in Read
+2. Multiple files OR pattern matching → read_file (MCP)
+3. Unknown location → smart_search then Read
+4. Large codebase + repeated access → codex_lens
+
+**File Editing**:
+1. Always try built-in Edit first
+2. Fails 1+ times → edit_file (MCP)
+3. Still fails → write_file (MCP)
+
+**Search**:
+1. External knowledge → Exa
+2. Exact pattern in small codebase → Built-in Grep
+3. Semantic/unknown location → smart_search
+4. Large codebase + repeated searches → codex_lens
+
+## Decision Triggers
+
+**Start with simplest tool** (Read, Edit, Grep)
+**Escalate to MCP tools** when built-ins fail or inappropriate
+**Use semantic search** for exploratory tasks
+**Use indexed search** for large, stable codebases
+**Use Exa** for external/public knowledge

.claude/workflows/context-search-strategy.md

@@ -1,9 +1,3 @@
----
-name: context-search-strategy
-description: Strategic guidelines for context search commands
-type: search-guideline
----
-
 # Context Search Strategy
 
 ## ⚡ Execution Environment

.claude/workflows/tool-strategy.md

@@ -1,88 +1,216 @@
-# Tool Strategy
+# Tool Strategy - When to Use What
 
-## ⚡ Exa Triggering Mechanisms
+> **Focus**: Decision triggers and selection logic, NOT syntax (already registered with Claude)
 
-**Auto-Trigger**:
-- User mentions "exa-code" or code-related queries → `mcp__exa__get_code_context_exa`
-- Need current web information → `mcp__exa__web_search_exa`
-
-**Manual Trigger**:
-- Complex API research → Exa Code Context
-- Real-time information needs → Exa Web Search
-
-## ⚡ CCW MCP Tools
-
-
-### edit_file
-
-**When to Use**: Edit tool fails 1+ times on same file
+## Quick Decision Tree
 
 ```
-mcp__ccw-tools__edit_file(path="file.py", oldText="old", newText="new")
-mcp__ccw-tools__edit_file(path="file.py", oldText="old", newText="new", dryRun=true)
-mcp__ccw-tools__edit_file(path="file.py", oldText="old", newText="new", replaceAll=true)
-mcp__ccw-tools__edit_file(path="file.py", mode="line", operation="insert_after", line=10, text="new line")
+Need context?
+├─ Exa available? → Use Exa (fastest, most comprehensive)
+├─ Large codebase (>500 files)? → codex_lens
+├─ Known files (<5)? → Read tool
+└─ Unknown files? → smart_search → Read tool
+
+Need to modify files?
+├─ Built-in Edit fails? → mcp__ccw-tools__edit_file
+└─ Still fails? → mcp__ccw-tools__write_file
+
+Need to search?
+├─ Semantic/concept search? → smart_search (mode=semantic)
+├─ Exact pattern match? → Grep tool
+└─ Multiple search modes needed? → smart_search (mode=auto)
 ```
 
-**Options**: `dryRun` (preview diff), `replaceAll`, `mode` (update|line), `operation`, `line`, `text`
+---
 
-### write_file
+## 1. Context Gathering Tools
 
-**When to Use**: Create new files or overwrite existing content
+### Exa (`mcp__exa__get_code_context_exa`)
+
+**Use When**:
+- ✅ Researching external APIs, libraries, frameworks
+- ✅ Need recent documentation (post-cutoff knowledge)
+- ✅ Looking for implementation examples in public repos
+- ✅ Comparing architectural patterns across projects
+
+**Don't Use When**:
+- ❌ Searching internal codebase (use smart_search/codex_lens)
+- ❌ Files already in working directory (use Read)
+
+**Trigger Indicators**:
+- User mentions specific library/framework names
+- Questions about "best practices", "how does X work"
+- Need to verify current API signatures
+
+---
+
+### read_file (`mcp__ccw-tools__read_file`)
+
+**Use When**:
+- ✅ Reading multiple related files at once (batch reading)
+- ✅ Need directory traversal with pattern matching
+- ✅ Searching file content with regex (`contentPattern`)
+- ✅ Want to limit depth/file count for large directories
+
+**Don't Use When**:
+- ❌ Single file read → Use built-in Read tool (faster)
+- ❌ Unknown file locations → Use smart_search first
+- ❌ Need semantic search → Use smart_search or codex_lens
+
+**Trigger Indicators**:
+- Need to read "all TypeScript files in src/"
+- Need to find "files containing TODO comments"
+- Want to read "up to 20 config files"
+
+**Advantages over Built-in Read**:
+- Batch operation (multiple files in one call)
+- Pattern-based filtering (glob + content regex)
+- Directory traversal with depth control
+
+---
+
+### codex_lens (`mcp__ccw-tools__codex_lens`)
+
+**Use When**:
+- ✅ Large codebase (>500 files) requiring repeated searches
+- ✅ Need semantic understanding of code relationships
+- ✅ Working across multiple sessions (persistent index)
+- ✅ Symbol-level navigation needed
+
+**Don't Use When**:
+- ❌ Small project (<100 files) → Use smart_search (no indexing overhead)
+- ❌ One-time search → Use smart_search or Grep
+- ❌ Files change frequently → Indexing overhead not worth it
+
+**Trigger Indicators**:
+- "Find all implementations of interface X"
+- "What calls this function across the codebase?"
+- Multi-session workflow on same codebase
+
+**Action Selection**:
+- `init`: First time in new codebase
+- `search`: Find code patterns
+- `search_files`: Find files by path/name pattern
+- `symbol`: Get symbols in specific file
+- `status`: Check if index exists/is stale
+- `clean`: Remove stale index
+
+---
+
+### smart_search (`mcp__ccw-tools__smart_search`)
+
+**Use When**:
+- ✅ Don't know exact file locations
+- ✅ Need concept/semantic search ("authentication logic")
+- ✅ Medium-sized codebase (100-500 files)
+- ✅ One-time or infrequent searches
+
+**Don't Use When**:
+- ❌ Known exact file path → Use Read directly
+- ❌ Large codebase + repeated searches → Use codex_lens
+- ❌ Exact pattern match → Use Grep (faster)
+
+**Mode Selection**:
+- `auto`: Let tool decide (default, safest)
+- `exact`: Know exact pattern, need fast results
+- `fuzzy`: Typo-tolerant file/symbol names
+- `semantic`: Concept-based ("error handling", "data validation")
+- `graph`: Dependency/relationship analysis
+
+**Trigger Indicators**:
+- "Find files related to user authentication"
+- "Where is the payment processing logic?"
+- "Locate database connection setup"
+
+---
+
+## 2. File Modification Tools
+
+### edit_file (`mcp__ccw-tools__edit_file`)
+
+**Use When**:
+- ✅ Built-in Edit tool failed 1+ times
+- ✅ Need dry-run preview before applying
+- ✅ Need line-based operations (insert_after, insert_before)
+- ✅ Need to replace all occurrences
+
+**Don't Use When**:
+- ❌ Built-in Edit hasn't failed yet → Try built-in first
+- ❌ Need to create new file → Use write_file
+
+**Trigger Indicators**:
+- Built-in Edit returns "old_string not found"
+- Built-in Edit fails due to whitespace/formatting
+- Need to verify changes before applying (dryRun=true)
+
+**Mode Selection**:
+- `mode=update`: Replace text (similar to built-in Edit)
+- `mode=line`: Line-based operations (insert_after, insert_before, delete)
+
+---
+
+### write_file (`mcp__ccw-tools__write_file`)
+
+**Use When**:
+- ✅ Creating brand new files
+- ✅ MCP edit_file still fails (last resort)
+- ✅ Need to completely replace file content
+- ✅ Need backup before overwriting
+
+**Don't Use When**:
+- ❌ File exists + small change → Use Edit tools
+- ❌ Built-in Edit hasn't been tried → Try built-in Edit first
+
+**Trigger Indicators**:
+- All Edit attempts failed
+- Need to create new file with specific content
+- User explicitly asks to "recreate file"
+
+---
+
+## 3. Decision Logic
+
+### File Reading Priority
 
 ```
-mcp__ccw-tools__write_file(path="file.txt", content="Hello")
-mcp__ccw-tools__write_file(path="file.txt", content="code with `backticks` and ${vars}", backup=true)
+1. Known single file? → Built-in Read
+2. Multiple files OR pattern matching? → mcp__ccw-tools__read_file
+3. Unknown location? → smart_search, then Read
+4. Large codebase + repeated access? → codex_lens
 ```
 
-**Options**: `backup`, `createDirectories`, `encoding`
-
-### read_file
-
-**When to Use**: Read multiple files, directory traversal, content search
+### File Editing Priority
 
 ```
-mcp__ccw-tools__read_file(paths="file.ts")                         # Single file
-mcp__ccw-tools__read_file(paths=["a.ts", "b.ts"])                  # Multiple files
-mcp__ccw-tools__read_file(paths="src/", pattern="*.ts")            # Directory + glob
-mcp__ccw-tools__read_file(paths="src/", contentPattern="TODO")     # Regex search
+1. Always try built-in Edit first
+2. Fails 1+ times? → mcp__ccw-tools__edit_file
+3. Still fails? → mcp__ccw-tools__write_file (last resort)
 ```
 
-**Options**: `pattern`, `contentPattern`, `maxDepth` (3), `includeContent` (true), `maxFiles` (50)
-
-### codex_lens
-
-**When to Use**: Code indexing, semantic search, cache management
+### Search Tool Priority
 
 ```
-mcp__ccw-tools__codex_lens(action="init", path=".")
-mcp__ccw-tools__codex_lens(action="search", query="function main", path=".")
-mcp__ccw-tools__codex_lens(action="search_files", query="pattern", limit=20)
-mcp__ccw-tools__codex_lens(action="symbol", file="src/main.py")
-mcp__ccw-tools__codex_lens(action="status")
-mcp__ccw-tools__codex_lens(action="config_show")
-mcp__ccw-tools__codex_lens(action="config_set", key="index_dir", value="/path")
-mcp__ccw-tools__codex_lens(action="config_migrate", newPath="/new/path")
-mcp__ccw-tools__codex_lens(action="clean", path=".")
-mcp__ccw-tools__codex_lens(action="clean", all=true)
+1. External knowledge? → Exa
+2. Exact pattern in small codebase? → Built-in Grep
+3. Semantic/unknown location? → smart_search
+4. Large codebase + repeated searches? → codex_lens
 ```
 
-**Actions**: `init`, `search`, `search_files`, `symbol`, `status`, `config_show`, `config_set`, `config_migrate`, `clean`
+---
 
-### smart_search
+## 4. Anti-Patterns
 
-**When to Use**: Quick search without indexing, natural language queries
+**Don't**:
+- Use codex_lens for one-time searches in small projects
+- Use smart_search when file path is already known
+- Use write_file before trying Edit tools
+- Use Exa for internal codebase searches
+- Use read_file for single file when Read tool works
 
-```
-mcp__ccw-tools__smart_search(query="function main", path=".")
-mcp__ccw-tools__smart_search(query="def init", mode="exact")
-mcp__ccw-tools__smart_search(query="authentication logic", mode="semantic")
-```
-
-**Modes**: `auto` (default), `exact`, `fuzzy`, `semantic`, `graph`
-
-### Fallback Strategy
-
-1. **Edit fails 1+ times** → `mcp__ccw-tools__edit_file`
-2. **Still fails** → `mcp__ccw-tools__write_file`
+**Do**:
+- Start with simplest tool (Read, Edit, Grep)
+- Escalate to MCP tools when built-ins fail
+- Use semantic search (smart_search) for exploratory tasks
+- Use indexed search (codex_lens) for large, stable codebases
+- Use Exa for external/public knowledge