docs: update READMEs with real search examples and usage

- Add practical Quick Start with npm link instructions
- Include real search output from testing
- Document threshold recommendations (0.7=precise, 0.25=exploratory)
- Add explore command documentation
- Show actual semantic search scores and results
- Include pro tips for scripting and workflows

Makes documentation reflect actual working functionality.

Author: prosdev

README.md

@@ -156,40 +156,65 @@ pnpm build
 
 ### Quick Start
 
+**For Local Development:**
+
 ```bash
-# Index your repository
-dev-agent index
+# Link the CLI globally for local testing
+cd packages/cli
+npm link
+
+# Now you can use 'dev' anywhere
+cd ~/your-project
+dev init
+dev index .
+```
 
-# Search with beautiful output
-dev-agent search "authentication logic"
+**Basic Commands:**
 
-# Get AI help planning work
-dev-agent plan --issue 42
+```bash
+# Index your repository
+dev index .
 
-# Discover patterns in your codebase  
-dev-agent explore "error handling patterns"
+# Semantic search (natural language queries work!)
+dev search "how do agents communicate"
+dev search "vector embeddings"
+dev search "error handling" --threshold 0.3
 
-# Create PR with AI-generated description
-dev-agent pr create
+# Explore code patterns
+dev explore pattern "test coverage utilities" --limit 5
+dev explore similar path/to/file.ts
 
-# JSON output for scripting
-dev-agent search "auth" --json | jq '.results[].file'
+# View statistics
+dev stats
 ```
 
-**Example output:**
-```
-🔍 Searching for "authentication"...
+**Real Example Output:**
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📄 auth/oauth.ts:45-67 (score: 0.92)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-   export class OAuth2Service {
-     authenticate(code: string) { ... }
-   }
+```bash
+$ dev search "vector embeddings" --threshold 0.3 --limit 3
+
+1. EmbeddingProvider (58.5% match)
+   File: packages/core/src/vector/types.ts:36-54
+   Signature: interface EmbeddingProvider
+   Doc: Generates vector embeddings from text
+
+2. EmbeddingDocument (51.0% match)
+   File: packages/core/src/vector/types.ts:8-12
+   Signature: interface EmbeddingDocument
 
-✨ Found 5 results in 42ms
+3. VectorStore (47.9% match)
+   File: packages/core/src/vector/types.ts:60-97
+   Signature: interface VectorStore
+   Doc: Stores and retrieves vector embeddings
+
+✔ Found 3 result(s)
 ```
 
+**Tips for Better Results:**
+- **Use natural language**: "how do agents communicate" works better than "agent message"
+- **Adjust thresholds**: Default is 0.7 (precise), use 0.25-0.4 for exploration
+- **Exact matches score 70-90%**: Semantic matches score 25-60%
+
 ### Current Status
 
 **In Progress:** Building core intelligence layer (scanner, vectors, indexer)

packages/cli/README.md

@@ -45,6 +45,28 @@ Options:
 - `-t, --threshold <number>` - Minimum similarity score 0-1 (default: 0.7)
 - `--json` - Output as JSON
 
+**Understanding Thresholds:**
+- `0.7` (default): Precise matches only
+- `0.4-0.6`: Balanced - good for most searches
+- `0.25-0.3`: Exploratory - finds related concepts
+- `0.0`: Return everything (useful for debugging)
+
+### Explore
+
+Explore code patterns and relationships:
+
+```bash
+# Find patterns using semantic search
+dev explore pattern "error handling" --limit 5
+
+# Find code similar to a file
+dev explore similar path/to/file.ts --limit 5
+```
+
+Options:
+- `-l, --limit <number>` - Maximum results (default: 10)
+- `-t, --threshold <number>` - Minimum similarity score (default: 0.7)
+
 ### Update
 
 Incrementally update the index with changed files:
@@ -107,22 +129,77 @@ The `.dev-agent.json` file configures the indexer:
 
 ## Examples
 
+### Basic Workflow
+
 ```bash
 # Initialize and index
 dev init
 dev index .
 
-# Search for code
-dev search "user authentication flow"
-dev search "database connection pool" --limit 5
+# View statistics
+dev stats
+# 📊 Files Indexed: 54, Vectors Stored: 566
+```
+
+### Semantic Search Examples
+
+```bash
+# Natural language queries work great!
+dev search "how do agents communicate" --threshold 0.3
+
+# Results:
+# 1. Message-Based Architecture (51.9% match)
+# 2. AgentContext (43.1% match)
+# 3. SubagentCoordinator.broadcastMessage (41.8% match)
+
+# Technical concept search
+dev search "vector embeddings" --threshold 0.3 --limit 3
+
+# Results:
+# 1. EmbeddingProvider (58.5% match)
+# 2. EmbeddingDocument (51.0% match)
+# 3. VectorStore (47.9% match)
+
+# Exact term matching (high scores!)
+dev search "RepositoryIndexer" --threshold 0.4
+
+# Results:
+# 1. RepositoryIndexer.index (85.7% match)
+# 2. RepositoryIndexer (75.4% match)
+```
+
+### Pattern Exploration
+
+```bash
+# Find patterns in your codebase
+dev explore pattern "test coverage utilities" --threshold 0.25
+
+# Results:
+# 1. Coverage Targets (56.0% match)
+# 2. 100% Coverage on Utilities (50.8% match)
+# 3. Testing (42.3% match)
+
+# Discover error handling patterns
+dev explore pattern "error handling" --threshold 0.3
+
+# Results:
+# 1. Handle Errors Gracefully (39.3% match)
+# 2. createErrorResponse (35.9% match)
+```
+
+### Pro Tips
+
+```bash
+# JSON output for scripting
+dev search "coordinator" --json | jq '.[].metadata.path' | sort -u
+
+# Lower threshold for exploration
+dev search "architectural patterns" --threshold 0.25 --limit 10
 
 # Keep index up to date
 dev update
 
-# View statistics
-dev stats
-
-# Clean and re-index
+# Clean and re-index if needed
 dev clean --force
 dev index . --force
 ```