diff --git a/README.md b/README.md
index 97ea332..07cdfc6 100644
--- a/README.md
+++ b/README.md
@@ -1,489 +1,134 @@
 # 🧠 Agentic Knowledge
 
-A way to handle knowledge cut-off: Provide all sources you and your development team need to your agents.
+**Search any documentation as if you had written it yourself**
 
-<div align="center">
-  <h3>The End of RAG. The Dawn of Agentic Search. Maybe.</h3>
-  <p><em>Intelligent navigation instructions that guide AI assistants through documentation using filesystem-like exploration instead of traditional retrieval</em></p>
-
-  <a href="https://github.com/yourusername/agentic-knowledge/blob/main/LICENSE">
-    <img src="https://img.shields.io/github/license/yourusername/agentic-knowledge.svg?style=for-the-badge" alt="License" />
-  </a>
-  <a href="https://linkedin.com/in/yourusername">
-    <img src="https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555" alt="LinkedIn" />
-  </a>
-</div>
+An MCP server that guides AI assistants to navigate documentation using their built-in tools (grep, file reading) instead of traditional RAG. Leverages massive context windows and agentic search patterns for precise, intelligent documentation discovery.
 
 ---
 
-## 🎯 What Is This?
-
-**Agentic Knowledge** represents a fundamental paradigm shift away from traditional Retrieval-Augmented Generation (RAG) toward **agentic search patterns**. Instead of chunking documents, computing embeddings, and retrieving fragments, this system provides **intelligent navigation instructions** that leverage the AI agent's existing tools (grep, ripgrep, file reading) and the explosion of context windows.
-
-### The Core Insight
-
-Modern AI assistants are **context-rich** (200K+ tokens) and equipped with powerful filesystem tools. Rather than building complex search infrastructure, we can guide them to navigate documentation intelligently—just like Claude Code revolutionized code analysis by ditching RAG for direct filesystem exploration.
-
-## 🪦 Why RAG is Dead
-
-_Inspired by [The RAG Obituary](https://www.nicolasbustamante.com/p/the-rag-obituary-killed-by-agents) by Nicolas Bustamante_
-
-Traditional RAG was a brilliant workaround for the **context-poor era** (GPT-4's 8K tokens). But it came with fundamental limitations:
-
-### The RAG Problem Stack
-
-```
-❌ Chunking destroys document relationships
-❌ Embeddings fail on precise terminology
-❌ Similarity search misses exact matches
-❌ Reranking adds latency and complexity
-❌ Context fragmentation loses coherence
-❌ Infrastructure burden is massive
-```
-
-### The Agentic Solution
-
-```
-✅ Direct filesystem navigation
-✅ Intelligent reference following
-✅ Complete document context
-✅ Zero infrastructure overhead
-✅ Sub-10ms response times
-✅ Deterministic, precise results
-```
-
-## 🔄 From Retrieval to Navigation
-
-Traditional RAG says: _"Here are 50 fragments that mention your keywords"_
-
-Agentic Knowledge says: _"Search for 'useState' in `./docs/react-18.2/hooks/`. If that doesn't help, try 'state management' in `./docs/patterns/`. Follow any 'See also' references you find."_
-
-The difference? **Guidance over fragments. Investigation over retrieval.**
-
-## 🏗 How It Works
-
-### MCP Server Integration
-
-Implements the [Model Context Protocol](https://modelcontextprotocol.io/) with two core tools:
-
-```typescript
-// Get navigation guidance for specific queries
-search_docs({
-  docset: "react-docs",
-  keywords: ["useEffect", "cleanup"],
-  generalized_keywords: ["lifecycle", "memory"],
-});
-
-// Discover available documentation sets
-list_docsets();
-```
-
-### Configuration-Driven Intelligence
-
-Simple `.knowledge/config.yaml` pattern:
-
-```yaml
-version: "1.0"
-docsets:
-  - id: react-docs
-    name: React Documentation
-    description: "React framework documentation"
-    sources:
-      - type: local_folder
-        paths: ["./docs/react-18.2"]
-    template: |
-      Search for '{{keywords}}' in {{local_path}}/hooks/. 
-      If not found, try '{{generalized_keywords}}' in {{local_path}}/patterns/.
-      Follow any cross-references you discover.
-```
-
-### The Navigation Response
-
-Instead of document fragments, you get **actionable instructions**:
-
-```
-Based on your React useEffect cleanup query:
-
-1. Start with `./docs/react-18.2/hooks/effect.md` - contains useEffect fundamentals
-2. Search for "cleanup function" patterns in `./docs/react-18.2/patterns/`
-3. Check `./examples/lifecycle/` for practical cleanup implementations
-4. Review `./docs/react-18.2/performance/memory.md` for memory leak prevention
-
-Focus on the cleanup function return pattern and dependency array management.
-```
-
-## 🚀 Why This Matters
+## 🎯 What Is This For?
 
-### The Context Revolution
+Give your AI assistant access to any documentation—yours or third-party—so it can find answers as naturally as you would. No embeddings, no vector databases, no complex infrastructure.
 
-- **2022**: GPT-4 had 8K tokens (~12 pages)
-- **2025**: Claude Sonnet has 200K tokens (~700 pages)
-- **Future**: Heading toward 2M+ tokens (~6,000 pages)
-
-### The Tool Evolution
-
-AI assistants now have sophisticated filesystem tools:
-
-- **Grep/Ripgrep**: Lightning-fast regex search through files
-- **Glob**: Direct file discovery by patterns
-- **Direct File Access**: Read complete documents in context
-- **Reference Following**: Navigate cross-references naturally
-
-### The Infrastructure Shift
-
-- **RAG**: Elasticsearch clusters, embedding models, rerankers, vector databases
-- **Agentic**: Simple YAML config, zero infrastructure, filesystem tools
-
-## 🎯 Core Principles
-
-### 1. **Guidance Over Search**
-
-Provide intelligent navigation instructions instead of search results
-
-### 2. **Context Abundance**
-
-Leverage massive context windows instead of working around limitations
-
-### 3. **Tool Evolution Compatibility**
-
-Instructions remain stable as agent capabilities evolve (grep → AST parsing → future tools)
-
-### 4. **Zero AI Dependency**
-
-Pure logic-based guidance for reliability and speed
-
-### 5. **Investigation Over Retrieval**
-
-Agents follow references and build understanding incrementally
+**Perfect for:**
+- 📚 **Project documentation** - Your team's internal docs, APIs, guides
+- 🔧 **Framework references** - React, TypeScript, MCP SDK, any library
+- 🏢 **Enterprise knowledge** - Company wikis, architecture docs, runbooks
+- 🌐 **Open source projects** - Clone any repo's docs for instant access
 
 ## 🚀 Quick Start
 
-### Installation
-
-```bash
-npm install -g agentic-knowledge
-# or
-npx agentic-knowledge
-```
-
-### Basic Setup
-
-1. **Create configuration directory**:
-
-```bash
-mkdir .knowledge
-```
-
-2. **Add configuration** (`.knowledge/config.yaml`):
-
-```yaml
-version: "1.0"
-docsets:
-  - id: my-docs
-    name: My Project Documentation
-    description: "Local project documentation"
-    sources:
-      - type: local_folder
-        paths: ["./docs"]
-
-  - id: react-docs
-    name: React Documentation
-    description: "Official React documentation from GitHub"
-    sources:
-      - type: git_repo
-        url: "https://github.com/facebook/react.git"
-        branch: "main"
-        paths: ["docs/"]
-```
-
-3. **Start the MCP server**:
-
-```bash
-agentic-knowledge
-```
-
-4. **Connect your AI assistant** using MCP protocol
-
-## 📋 Configuration Guide
-
-### Local Folder Sources
-
-For documentation stored locally in your project:
-
-```yaml
-docsets:
-  - id: my-project
-    name: My Project Docs
-    sources:
-      - type: local_folder
-        paths:
-          - "./docs" # Single directory
-          - "./guides" # Multiple directories
-          - "./api/README.md" # Specific files
-```
-
-**Benefits:**
-
-- ✅ **No file duplication** - creates symlinks to original locations
-- ✅ **Real-time updates** - changes immediately visible
-- ✅ **Relative paths** - returns clean relative paths for LLM navigation
-
-### Git Repository Sources
-
-For documentation from remote repositories:
-
-```yaml
-docsets:
-  - id: external-docs
-    name: External Documentation
-    sources:
-      - type: git_repo
-        url: "https://github.com/owner/repo.git"
-        branch: "main" # Optional, defaults to main
-        paths: ["docs/", "README.md"] # Optional, extracts specific paths
-```
-
-**Benefits:**
-
-- ✅ **Automatic downloads** - fetches latest documentation
-- ✅ **Selective extraction** - only downloads specified paths
-- ✅ **Branch selection** - target specific branches or tags
-
-### Mixed Configuration
-
-Combine local and remote sources in one configuration:
-
-```yaml
-version: "1.0"
-docsets:
-  - id: local-guides
-    name: Local User Guides
-    sources:
-      - type: local_folder
-        paths: ["./docs/guides"]
-
-  - id: api-reference
-    name: API Reference
-    sources:
-      - type: git_repo
-        url: "https://github.com/company/api-docs.git"
-        paths: ["reference/"]
-
-  - id: mixed-sources
-    name: Combined Documentation
-    sources:
-      - type: local_folder
-        paths: ["./internal-docs"]
-      - type: git_repo
-        url: "https://github.com/external/docs.git"
-```
-
-## 🎯 How to Use
-
-### Step 1: Set Up Your Documentation
-
-Create a `.knowledge/config.yaml` file in your project root:
-
-```yaml
-version: "1.0"
-docsets:
-  - id: my-project
-    name: My Project Documentation
-    description: "Main project documentation"
-    sources:
-      - type: local_folder
-        paths: ["./docs", "./README.md"]
-```
-
-### Step 2: Start the MCP Server
-
-```bash
-# Install globally
-npm install -g agentic-knowledge
-
-# Start the server
-agentic-knowledge
-```
-
-The server will:
-
-- ✅ Create symlinks for local folders in `.knowledge/docsets/`
-- ✅ Validate your configuration
-- ✅ Start listening for MCP requests
-
-### Step 3: Connect Your AI Assistant
-
-Configure your AI assistant (Claude Desktop, etc.) to use the MCP server:
+### 1. Configure an MCP Client
 
+Add to your coding agent config something along the lines of 
 ```json
 {
   "mcpServers": {
     "agentic-knowledge": {
-      "command": "agentic-knowledge"
+      "command": "npx",
+      "args": ["-y", "agentic-knowledge-mcp"]
     }
   }
 }
 ```
 
-### Step 4: Search Your Documentation
 
-Use the `search_docs` tool in your AI assistant:
+### 2. Set Up Your First Docset
 
-```
-search_docs({
-  docset_id: "my-project",
-  keywords: "authentication setup",
-  generalized_keywords: "login, auth, security"
-})
-```
-
-**Response:**
-
-```
-# 📚 Search My Project Documentation
+**Option A: Use the CLI (Recommended)**
 
-**Primary terms:** authentication setup
-**Related terms:** login, auth, security
-**Location:** docs
-
-## 🔍 Search Strategy
-
-1. **Start with Specific Terms**
-   Use your text search tools (grep, rg, ripgrep) to search for: `authentication setup`
+```bash
+# For a Git repository
+npx agentic-knowledge-mcp create \
+  --preset git-repo \
+  --id react-docs \
+  --name "React Documentation" \
+  --url https://github.com/facebook/react.git
 
-2. **Expand to Related Terms**
-   If initial search doesn't yield results, try: `login, auth, security`
+# Initialize (downloads the docs)
+npx agentic-knowledge-mcp init react-docs
 
-3. **What to Avoid**
-   Skip these directories: `node_modules/`, `.git/`, `.knowledge/`
+# The MCP server starts automatically when Claude Desktop launches
 ```
 
-### Step 5: Follow the Guidance
-
-Your AI assistant will use the provided search strategy to:
-
-1. 🔍 Search your documentation with the suggested terms
-2. 📂 Navigate to the right files and directories
-3. 🎯 Find exactly what you're looking for
-4. 🔗 Follow cross-references and related content
+**Option B: Manual Configuration**
 
-## 💡 Pro Tips
-
-### Local Development Workflow
+Create `.knowledge/config.yaml`:
 
 ```yaml
-# Perfect for active development
+version: "1.0"
 docsets:
-  - id: current-project
-    name: Current Project
+  - id: my-docs
+    name: My Project Documentation
     sources:
       - type: local_folder
-        paths: ["./docs", "./README.md", "./CHANGELOG.md"]
+        paths: ["./docs"]
 ```
 
-**Benefits:**
 
-- Changes in your docs are immediately available
-- No copying or syncing needed
-- Works with any file type
+### 3. Use It
 
-### Multi-Repository Setup
+Your AI assistant now has access to `search_docs` and `list_docsets` tools. Ask questions naturally:
 
-```yaml
-# Combine multiple sources
-docsets:
-  - id: frontend-docs
-    name: Frontend Documentation
-    sources:
-      - type: local_folder
-        paths: ["./frontend/docs"]
-      - type: git_repo
-        url: "https://github.com/company/design-system.git"
-        paths: ["docs/"]
-
-  - id: backend-docs
-    name: Backend Documentation
-    sources:
-      - type: git_repo
-        url: "https://github.com/company/api-docs.git"
-        branch: "main"
 ```
-
-### Advanced Search Strategies
-
-Use specific and generalized keywords for better results:
-
-```javascript
-// ✅ Good: Specific + General
-search_docs({
-  docset_id: "react-docs",
-  keywords: "useEffect cleanup function",
-  generalized_keywords: "hooks, lifecycle, memory management",
-});
-
-// ❌ Too vague
-search_docs({
-  docset_id: "react-docs",
-  keywords: "react",
-  generalized_keywords: "javascript",
-});
+"How do I implement a cleanup function in React useEffect?"
+"Show me the authentication setup in our docs"
+"Find examples of rate limiting in the API docs"
 ```
 
-## 📊 Performance vs RAG
-
-| Metric             | Traditional RAG           | Agentic Knowledge |
-| ------------------ | ------------------------- | ----------------- |
-| **Setup Time**     | Hours (indexing)          | Seconds (config)  |
-| **Response Time**  | 300-2000ms                | <10ms             |
-| **Infrastructure** | Elasticsearch + Vector DB | Zero              |
-| **Maintenance**    | High (reindexing)         | None              |
-| **Accuracy**       | Fragment-based            | Complete context  |
-| **Cost**           | High (compute)            | Minimal           |
+The assistant will receive intelligent navigation instructions and use grep/file reading to find the exact information.
 
-## 🔬 The Future of Knowledge Systems
+## 📖 Documentation
 
-We're entering the **post-retrieval age**. The winners won't be those with the biggest vector databases, but those who design the smartest navigation systems for abundant context.
+- **[User Guide](./USER_GUIDE.md)** - Detailed CLI commands, lifecycle, configuration
+- **[Examples](./examples/)** - Configuration examples and integration guides
+- **[Testing Guide](./TESTING.md)** - Comprehensive testing documentation
 
-**RAG was training wheels**—useful, necessary, but temporary. The future belongs to systems that read, navigate, and reason end-to-end.
+## 💡 How and Why It Works
 
-## 🚀 Local Development & Installation
+### The Paradigm Shift
 
-### Installing from Source (Before NPM Publication)
+Traditional RAG (Retrieval-Augmented Generation) was built for the **context-poor era** when models had 8K token limits. It:
+- Chunks documents (losing relationships)
+- Computes embeddings (missing precise terminology)
+- Retrieves fragments (losing context)
+- Requires massive infrastructure (vector DBs, rerankers)
 
-Since the packages aren't published to npm yet, you can install them locally:
+**Agentic Knowledge** leverages modern AI capabilities:
+- ✅ **200K+ token context windows** - Can read entire documentation sets
+- ✅ **Powerful filesystem tools** - grep, ripgrep, file reading built-in
+- ✅ **Intelligent navigation** - Provides search strategies, not fragments
+- ✅ **Zero infrastructure** - Just a config file and your docs
 
-1. **Build all packages:**
+### From Retrieval to Navigation
 
-   ```bash
-   pnpm install
-   pnpm build
-   ```
+**Traditional RAG says:**
+*"Here are 50 fragments that mention your keywords"*
 
-2. **Create local installation packages:**
+**Agentic Knowledge says:**
+*"Search for 'useState' in `./docs/react-18.2/hooks/`. If that doesn't help, try 'state management' in `./docs/patterns/`. Follow any 'See also' references you find."*
 
-   ```bash
-   pnpm run pack:local
-   ```
+**The difference?** Guidance over fragments. Investigation over retrieval.
 
-   This creates `dist-local/` directory with packages that have workspace dependencies converted to relative file paths.
+### How It Actually Works
 
-3. **Install the MCP server locally:**
+1. **Configure docsets** - Point to local folders or Git repositories
+2. **Initialize** - Downloads/symlinks documentation to `.knowledge/docsets/`
+3. **MCP server** - Exposes `search_docs` and `list_docsets` tools
+4. **AI searches** - Gets navigation instructions, uses grep/file tools
+5. **Finds answers** - Reads complete documents with full context
 
-   ```bash
-   # Option 1: Install from tarball
-   cd dist-local/mcp-server && npm pack
-   npm install -g codemcp-knowledge-mcp-server-0.1.0.tgz
+**Performance:**
+- **Setup**: Seconds (vs hours for RAG indexing)
+- **Response**: <10ms (vs 300-2000ms for RAG)
+- **Infrastructure**: None (vs Elasticsearch + Vector DB)
+- **Accuracy**: Complete context (vs fragment-based)
 
-   # Option 2: Install directly from directory
-   npm install -g ./dist-local/mcp-server/
-   ```
+### Inspired By
 
-4. **Verify installation:**
-   ```bash
-   agentic-knowledge --help
-   ```
+This approach is inspired by [The RAG Obituary](https://www.nicolasbustamante.com/p/the-rag-obituary-killed-by-agents) by Nicolas Bustamante and how Claude Code revolutionized code analysis by ditching RAG for direct filesystem exploration.
 
-### Development
+## 🚀 Local Development
 
 ```bash
 # Install dependencies
@@ -497,27 +142,9 @@ pnpm test
 
 # Build all packages
 pnpm build
-
-# Format and lint
-pnpm format
-pnpm lint
 ```
 
-## 🧪 Development Status
-
-**Current Phase**: Finalization ✅
-
-- ✅ Core implementation complete (107 tests passing)
-- ✅ MCP protocol compliance verified
-- ✅ Performance validated (0.47ms response time)
-- ✅ Full documentation and examples
-- ⚠️ Ready for community feedback and real-world testing
-
-## 📚 Examples & Documentation
-
-- [`examples/`](./examples/) - Configuration examples and integration guides
-- [`TESTING.md`](./TESTING.md) - Comprehensive testing documentation
-- [Architecture docs](./.vibe/docs/) - Detailed technical specifications
+See [User Guide](./USER_GUIDE.md) for installation from source.
 
 ## 🤝 Contributing
 
diff --git a/USER_GUIDE.md b/USER_GUIDE.md
new file mode 100644
index 0000000..a54702d
--- /dev/null
+++ b/USER_GUIDE.md
@@ -0,0 +1,594 @@
+# Agentic Knowledge User Guide
+
+Complete guide to using Agentic Knowledge for managing and searching documentation.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Docset Lifecycle](#docset-lifecycle)
+- [CLI Commands](#cli-commands)
+- [Configuration Guide](#configuration-guide)
+- [Complete Workflows](#complete-workflows)
+- [MCP Integration](#mcp-integration)
+- [Troubleshooting](#troubleshooting)
+
+## Installation
+
+### From NPM (Recommended)
+
+```bash
+# Install in your project
+npm install agentic-knowledge
+
+# Or use directly with npx (no installation needed)
+npx agentic-knowledge --help
+```
+
+### From Source
+
+Since the packages aren't published to npm yet, you can install them locally:
+
+1. **Build all packages:**
+
+   ```bash
+   pnpm install
+   pnpm build
+   ```
+
+2. **Create local installation packages:**
+
+   ```bash
+   pnpm run pack:local
+   ```
+
+   This creates `dist-local/` directory with packages that have workspace dependencies converted to relative file paths.
+
+3. **Install the MCP server locally:**
+
+   ```bash
+   # Option 1: Install from tarball
+   cd dist-local/mcp-server && npm pack
+   npm install -g codemcp-knowledge-mcp-server-0.1.0.tgz
+
+   # Option 2: Install directly from directory
+   npm install -g ./dist-local/mcp-server/
+   ```
+
+4. **Verify installation:**
+   ```bash
+   agentic-knowledge --help
+   ```
+
+## Docset Lifecycle
+
+A docset goes through the following phases:
+
+```
+1. CREATE     → Configure docset (manually edit config.yaml or use CLI presets)
+2. INITIALIZE → Download and prepare documentation files
+3. USE        → Search and navigate via MCP server
+4. REFRESH    → Update documentation as needed
+```
+
+### Phase 1: CREATE
+
+Define a docset in `.knowledge/config.yaml` either manually or using the CLI `create` command.
+
+### Phase 2: INITIALIZE
+
+Download and prepare documentation files to make them searchable. For git repos, this clones and filters the content. For local folders, this creates symlinks.
+
+### Phase 3: USE
+
+The MCP server exposes the docsets to AI assistants via the `search_docs` and `list_docsets` tools.
+
+### Phase 4: REFRESH
+
+Update already-initialized docsets with the latest content from their sources.
+
+## CLI Commands
+
+The `agentic-knowledge` CLI provides commands to manage your documentation lifecycle. When you run `agentic-knowledge` without arguments, it starts the MCP server. With arguments, it executes CLI commands.
+
+### `create` - Create New Docset Configuration
+
+Create docset configurations quickly using presets. Alternatively, you can manually edit `.knowledge/config.yaml` - this command is just a convenience tool that does it for you.
+
+**Git Repository Preset:**
+```bash
+npx agentic-knowledge create \
+  --preset git-repo \
+  --id mcp-sdk \
+  --name "MCP TypeScript SDK" \
+  --url https://github.com/modelcontextprotocol/typescript-sdk.git \
+  --branch main
+```
+
+**Local Folder Preset:**
+```bash
+npx agentic-knowledge create \
+  --preset local-folder \
+  --id my-docs \
+  --name "My Documentation" \
+  --path ./docs
+```
+
+**Options:**
+- `--preset <type>`: Choose preset (`git-repo` or `local-folder`)
+- `--id <id>`: Unique identifier for the docset
+- `--name <name>`: Human-readable name
+- `--url <url>`: Git repository URL (for git-repo preset)
+- `--branch <branch>`: Git branch (optional, defaults to main)
+- `--path <path>`: Local directory path (for local-folder preset)
+
+The `create` command:
+- ✅ Creates or updates `.knowledge/config.yaml`
+- ✅ Validates docset ID uniqueness
+- ✅ For local folders, creates symlinks immediately
+- ✅ For git repos, prepares configuration for initialization
+
+### `init` - Initialize Docset Sources
+
+Initialize a configured docset by downloading and preparing documentation. Use this for **first-time setup**.
+
+```bash
+# Initialize a specific docset
+npx agentic-knowledge init mcp-sdk
+
+# Force re-initialization (start completely fresh)
+npx agentic-knowledge init mcp-sdk --force
+
+# Use custom config path
+npx agentic-knowledge init mcp-sdk --config /path/to/config.yaml
+```
+
+**When to use:**
+- Setting up a docset for the first time
+- With `--force`: Completely reset a docset (deletes everything and re-downloads)
+
+**What happens during initialization:**
+
+1. **For Git Repositories:**
+   - Clones repository to temporary directory
+   - Extracts specified paths (if configured)
+   - Applies smart filtering (excludes `node_modules/`, build artifacts, etc.)
+   - Copies documentation to `.knowledge/docsets/{id}/`
+   - Creates metadata files for change tracking
+
+2. **For Local Folders:**
+   - Creates symlinks in `.knowledge/docsets/{id}/`
+   - No file duplication
+   - Changes are immediately visible
+
+3. **Creates Metadata:**
+   - `.agentic-metadata.json` - Overall docset information
+   - `.agentic-source-{index}.json` - Per-source tracking with content hashes
+
+**Directory structure after init:**
+```
+.knowledge/
+├── config.yaml
+├── .gitignore (auto-created)
+└── docsets/
+    └── mcp-sdk/
+        ├── .agentic-metadata.json
+        ├── .agentic-source-0.json
+        └── [documentation files...]
+```
+
+### `status` - Check Docset Status
+
+View the status of all docsets and their sources:
+
+```bash
+# Basic status
+npx agentic-knowledge status
+
+# Detailed status with source information
+npx agentic-knowledge status --verbose
+
+# Use custom config
+npx agentic-knowledge status --config /path/to/config.yaml
+```
+
+**Example output:**
+```
+📊 Docset Status
+
+mcp-sdk (MCP TypeScript SDK)
+   Initialized | 45 files | 2 source(s) loaded
+   Initialized: 2024-11-20
+
+react-docs (React Documentation)
+   Initialized | 120 files | 1 source(s) loaded
+   Initialized: 2024-11-15
+
+api-docs (API Documentation)
+   Not initialized | 1 source(s) configured
+
+   💡 Run: agentic-knowledge init api-docs
+```
+
+### `refresh` - Update Documentation
+
+Update already-initialized docsets with latest content. This is a **smart, incremental update**.
+
+```bash
+# Refresh all docsets
+npx agentic-knowledge refresh
+
+# Refresh specific docset
+npx agentic-knowledge refresh mcp-sdk
+
+# Force refresh (ignore throttle)
+npx agentic-knowledge refresh mcp-sdk --force
+
+# Use custom config
+npx agentic-knowledge refresh --config /path/to/config.yaml
+```
+
+**Smart refresh logic:**
+- Checks Git commit hash to detect changes
+- Skips refresh if no changes detected
+- Skips refresh if updated within 1 hour (unless `--force`)
+- Updates in place (preserves metadata)
+
+**When to use:**
+- Getting latest updates from git repositories
+- Routine maintenance/updates
+- Checking for new content
+
+**Key difference from `init --force`:**
+- `init --force`: Deletes everything and starts fresh (destructive)
+- `refresh`: Checks for changes and updates incrementally (smart)
+
+## Configuration Guide
+
+### Configuration File Location
+
+Place your configuration file at `.knowledge/config.yaml` in your project root.
+
+### Local Folder Sources
+
+For documentation stored locally in your project:
+
+```yaml
+docsets:
+  - id: my-project
+    name: My Project Docs
+    sources:
+      - type: local_folder
+        paths:
+          - "./docs" # Single directory
+          - "./guides" # Multiple directories
+          - "./api/README.md" # Specific files
+```
+
+**Benefits:**
+
+- ✅ **No file duplication** - creates symlinks to original locations
+- ✅ **Real-time updates** - changes immediately visible
+- ✅ **Relative paths** - returns clean relative paths for LLM navigation
+
+### Git Repository Sources
+
+For documentation from remote repositories:
+
+```yaml
+docsets:
+  - id: external-docs
+    name: External Documentation
+    sources:
+      - type: git_repo
+        url: "https://github.com/owner/repo.git"
+        branch: "main" # Optional, defaults to main
+        paths: ["docs/", "README.md"] # Optional, extracts specific paths
+```
+
+**Benefits:**
+
+- ✅ **Automatic downloads** - fetches latest documentation
+- ✅ **Selective extraction** - only downloads specified paths
+- ✅ **Branch selection** - target specific branches or tags
+
+### Mixed Configuration
+
+Combine local and remote sources in one configuration:
+
+```yaml
+version: "1.0"
+docsets:
+  - id: local-guides
+    name: Local User Guides
+    sources:
+      - type: local_folder
+        paths: ["./docs/guides"]
+
+  - id: api-reference
+    name: API Reference
+    sources:
+      - type: git_repo
+        url: "https://github.com/company/api-docs.git"
+        paths: ["reference/"]
+
+  - id: mixed-sources
+    name: Combined Documentation
+    sources:
+      - type: local_folder
+        paths: ["./internal-docs"]
+      - type: git_repo
+        url: "https://github.com/external/docs.git"
+```
+
+### Advanced: Custom Search Templates
+
+You can customize the search instructions provided to AI assistants:
+
+```yaml
+version: "1.0"
+docsets:
+  - id: react-docs
+    name: React Documentation
+    description: "React framework documentation"
+    sources:
+      - type: local_folder
+        paths: ["./docs/react-18.2"]
+    template: |
+      Search for '{{keywords}}' in {{local_path}}/hooks/.
+      If not found, try '{{generalized_keywords}}' in {{local_path}}/patterns/.
+      Follow any cross-references you discover.
+```
+
+**Template variables:**
+- `{{keywords}}` - Primary search terms
+- `{{generalized_keywords}}` - Broader context terms
+- `{{local_path}}` - Path to the docset
+
+## Complete Workflows
+
+### Workflow 1: Local Project Documentation
+
+```bash
+# 1. Create config for local docs
+npx agentic-knowledge create \
+  --preset local-folder \
+  --id my-project \
+  --name "My Project Docs" \
+  --path ./docs
+
+# 2. Check status
+npx agentic-knowledge status
+
+# 3. Configure Claude Desktop (see MCP Integration section)
+# The server runs automatically when Claude launches
+```
+
+No initialization needed - local folders use symlinks!
+
+### Workflow 2: External Git Repository
+
+```bash
+# 1. Create docset for a Git repository
+npx agentic-knowledge create \
+  --preset git-repo \
+  --id react-docs \
+  --name "React Documentation" \
+  --url https://github.com/facebook/react.git \
+  --branch main
+
+# 2. Initialize the docset (downloads docs)
+npx agentic-knowledge init react-docs
+
+# 3. Check status
+npx agentic-knowledge status
+
+# 4. Configure Claude Desktop (see MCP Integration section)
+# The server runs automatically when Claude launches
+
+# Later: Update documentation
+npx agentic-knowledge refresh react-docs
+```
+
+### Workflow 3: Multi-Repository Setup
+
+```bash
+# Set up multiple docsets
+npx agentic-knowledge create --preset git-repo --id frontend-docs --name "Frontend Docs" --url https://github.com/company/frontend.git
+npx agentic-knowledge create --preset git-repo --id backend-docs --name "Backend Docs" --url https://github.com/company/backend.git
+npx agentic-knowledge create --preset local-folder --id internal-docs --name "Internal Docs" --path ./docs
+
+# Initialize git repos
+npx agentic-knowledge init frontend-docs
+npx agentic-knowledge init backend-docs
+
+# Check all statuses
+npx agentic-knowledge status --verbose
+
+# Configure Claude Desktop (see MCP Integration section)
+# The server runs automatically when Claude launches
+```
+
+## MCP Integration
+
+### MCP Server
+
+When you run `agentic-knowledge` without arguments, it starts an MCP server that exposes two tools:
+
+#### `search_docs` Tool
+
+Get navigation guidance for specific queries:
+
+```typescript
+search_docs({
+  docset_id: "react-docs",
+  keywords: "useEffect cleanup",
+  generalized_keywords: "hooks lifecycle memory",
+});
+```
+
+**Returns:**
+```json
+{
+  "instructions": "Search for 'useEffect cleanup' in .knowledge/docsets/react-docs/hooks/...",
+  "search_terms": "useEffect cleanup",
+  "generalized_search_terms": "hooks lifecycle memory",
+  "path": ".knowledge/docsets/react-docs"
+}
+```
+
+#### `list_docsets` Tool
+
+Discover available documentation sets:
+
+```typescript
+list_docsets();
+```
+
+**Returns:**
+```
+Found 2 available docset(s):
+
+**react-docs** (React Documentation)
+  Description: Official React documentation
+  Path: .knowledge/docsets/react-docs
+
+**my-docs** (My Project Documentation)
+  Description: Internal project documentation
+  Path: docs
+```
+
+### Configuring MCP Clients
+
+#### Claude Desktop
+
+**Configuration file location:**
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/Claude/claude_desktop_config.json`
+
+**Option 1: Using npx (recommended)**
+
+```json
+{
+  "mcpServers": {
+    "agentic-knowledge": {
+      "command": "npx",
+      "args": ["-y", "agentic-knowledge"]
+    }
+  }
+}
+```
+
+The `-y` flag automatically confirms the installation prompt from npx.
+
+**Option 2: Project-specific installation**
+
+If you have agentic-knowledge installed in a specific project:
+
+```json
+{
+  "mcpServers": {
+    "agentic-knowledge": {
+      "command": "npx",
+      "args": ["-y", "agentic-knowledge"],
+      "cwd": "/absolute/path/to/your/project"
+    }
+  }
+}
+```
+
+This runs the server in your project directory, making it use your project's `.knowledge/config.yaml`.
+
+**Option 3: Global npm installation**
+
+If you installed globally with `npm install -g agentic-knowledge`:
+
+```json
+{
+  "mcpServers": {
+    "agentic-knowledge": {
+      "command": "agentic-knowledge"
+    }
+  }
+}
+```
+
+**After configuration:**
+1. Restart Claude Desktop
+2. The server starts automatically in the background
+3. Look for the 🔌 icon in Claude Desktop to verify the connection
+
+#### Other MCP Clients
+
+For other MCP clients, use:
+- **Command**: `npx`
+- **Args**: `["-y", "agentic-knowledge"]`
+- **Transport**: stdio
+
+The server will start automatically when the MCP client launches.
+
+### Using in AI Conversations
+
+Once configured, simply ask questions:
+
+```
+"How do I implement authentication in our API?"
+"Show me examples of React hooks cleanup"
+"Find the rate limiting configuration"
+```
+
+The AI assistant will:
+1. Call `search_docs` with appropriate keywords
+2. Receive navigation instructions
+3. Use grep/ripgrep to search the documentation
+4. Read relevant files with full context
+5. Provide accurate answers
+
+## Troubleshooting
+
+### MCP Server Won't Start
+
+**Error**: "No configuration file found"
+
+**Solution**: Create `.knowledge/config.yaml` or the server will start with no docsets (shows setup instructions in tool descriptions).
+
+### Docset Not Initialized
+
+**Error**: "Docset 'X' is not initialized"
+
+**Solution**: Run `agentic-knowledge init X`
+
+### Git Clone Failures
+
+**Error**: "Failed to clone repository"
+
+**Solutions:**
+- Check internet connection
+- Verify repository URL is correct
+- Ensure you have access to private repositories
+- Try with `--branch` flag if default branch isn't `main`
+
+### Status Shows Old Data
+
+**Solution**: Run `agentic-knowledge refresh <docset-id>` to update
+
+### Symlinks Not Working
+
+**Issue**: Local folder changes not reflected
+
+**Solutions:**
+- Verify the source paths exist
+- Check file permissions
+- Re-run `agentic-knowledge create` with the local folder preset
+
+### Search Not Finding Results
+
+**Tips:**
+- Try broader keywords with `generalized_keywords`
+- Check the docset is initialized: `agentic-knowledge status`
+- Verify the documentation actually contains the terms
+- Use verbose status to see which files are included
+
+---
+
+For more information, see the [README](./README.md) or check the [examples](./examples/) directory.
diff --git a/packages/cli/src/__tests__/create-command.test.ts b/packages/cli/src/__tests__/create-command.test.ts
index 4127b24..6873fc2 100644
--- a/packages/cli/src/__tests__/create-command.test.ts
+++ b/packages/cli/src/__tests__/create-command.test.ts
@@ -6,7 +6,6 @@ import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { promises as fs } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { execSync } from "node:child_process";
 
 describe("create command", () => {
   let testDir: string;
diff --git a/packages/cli/src/commands/create.ts b/packages/cli/src/commands/create.ts
index bf13983..2d6f3a5 100644
--- a/packages/cli/src/commands/create.ts
+++ b/packages/cli/src/commands/create.ts
@@ -137,7 +137,7 @@ async function createLocalFolderDocset(options: any): Promise<DocsetConfig> {
     if (!stat.isDirectory()) {
       throw new Error(`Path is not a directory: ${options.path}`);
     }
-  } catch (error) {
+  } catch {
     throw new Error(`Path does not exist: ${options.path}`);
   }
 
diff --git a/packages/cli/src/commands/status.ts b/packages/cli/src/commands/status.ts
index f8e639f..0cf4890 100644
--- a/packages/cli/src/commands/status.ts
+++ b/packages/cli/src/commands/status.ts
@@ -178,12 +178,14 @@ function displaySummary(statuses: DocsetStatus[]) {
     }
 
     if (!initialized) {
+      console.log(`${chalk.bold(docset.id)} (${docset.name})`);
       console.log(
-        `${chalk.yellow("⚠️")} ${chalk.bold(docset.id)} - ${chalk.yellow("Not initialized")}`,
-      );
-      console.log(
-        chalk.gray(`   ${docset.sources?.length || 0} source(s) configured`),
+        chalk.gray(
+          `   Not initialized | ${docset.sources?.length || 0} source(s) configured`,
+        ),
       );
+      console.log();
+      console.log(chalk.blue(`   💡 Run: agentic-knowledge init ${docset.id}`));
       continue;
     }
 
@@ -194,38 +196,17 @@ function displaySummary(statuses: DocsetStatus[]) {
       continue;
     }
 
-    // Calculate status
-    const lastActivity = metadata.last_refreshed || metadata.initialized_at;
-    const lastActivityTime = new Date(lastActivity);
-    const timeSince = Date.now() - lastActivityTime.getTime();
-    const hoursSince = timeSince / (1000 * 60 * 60);
-    const daysSince = timeSince / (1000 * 60 * 60 * 24);
-
-    let timeDisplay;
-    let statusIcon;
-
-    if (hoursSince < 1) {
-      timeDisplay = `${Math.round(hoursSince * 60)} minutes ago`;
-      statusIcon = chalk.green("✅");
-    } else if (hoursSince < 24) {
-      timeDisplay = `${Math.round(hoursSince)} hours ago`;
-      statusIcon = chalk.green("✅");
-    } else if (daysSince < 7) {
-      timeDisplay = `${Math.round(daysSince)} days ago`;
-      statusIcon = chalk.yellow("⚠️");
-    } else {
-      timeDisplay = `${Math.round(daysSince)} days ago`;
-      statusIcon = chalk.red("🔄");
-    }
+    // Format initialization date
+    const initDate = new Date(metadata.initialized_at);
+    const dateDisplay = initDate.toISOString().split("T")[0]; // YYYY-MM-DD format
 
-    console.log(
-      `${statusIcon} ${chalk.bold(docset.id)} - ${chalk.gray(metadata.total_files)} files`,
-    );
+    console.log(`${chalk.bold(docset.id)} (${docset.name})`);
     console.log(
       chalk.gray(
-        `   Last updated: ${timeDisplay} | ${sources.length}/${metadata.sources_count} sources loaded`,
+        `   Initialized | ${metadata.total_files} files | ${sources.length}/${metadata.sources_count} source(s) loaded`,
       ),
     );
+    console.log(chalk.gray(`   Initialized: ${dateDisplay}`));
   }
 }
 
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
index edce012..e6dc344 100644
--- a/packages/core/src/types.ts
+++ b/packages/core/src/types.ts
@@ -119,6 +119,8 @@ export interface TemplateContext {
 
 /**
  * Error types that can occur in the core system
+ * Note: Linter may warn about "unused" enum values, but these are used throughout
+ * the codebase as ErrorType.CONFIG_NOT_FOUND, etc. The warnings are false positives.
  */
 export enum ErrorType {
   CONFIG_NOT_FOUND = "CONFIG_NOT_FOUND",
diff --git a/packages/mcp-server/src/__tests__/integration.test.ts b/packages/mcp-server/src/__tests__/integration.test.ts
index d755bd9..fc92213 100644
--- a/packages/mcp-server/src/__tests__/integration.test.ts
+++ b/packages/mcp-server/src/__tests__/integration.test.ts
@@ -91,7 +91,7 @@ docsets:
       const server = createAgenticKnowledgeServer();
 
       // Create a mock request handler to capture tool descriptions
-      let toolsResponse: any = null;
+      let _toolsResponse: any = null;
 
       // We can't easily test the actual ListToolsRequestSchema handler directly,
       // but we can verify the server creates without errors and our configuration loads
@@ -149,5 +149,55 @@ docsets:
       // Server creation should succeed even if config loading will fail later
       // This tests that server initialization is robust
     });
+
+    it("should fail when searching uninitialized docset", async () => {
+      // Create a docset with git_repo source that is NOT initialized
+      const uninitializedConfig = `
+version: "1.0"
+docsets:
+  - id: "uninitialized-docs"
+    name: "Uninitialized Documentation"
+    description: "A docset that hasn't been initialized yet"
+    sources:
+      - type: git_repo
+        url: "https://github.com/example/repo.git"
+    local_path: ".knowledge/docsets/uninitialized-docs"
+`;
+      await fs.writeFile(tempConfigPath, uninitializedConfig);
+
+      const server = createAgenticKnowledgeServer();
+
+      // Create the docset directory (simulating what the create command does)
+      // but don't create the .agentic-metadata.json file (which init command creates)
+      const docsetDir = join(
+        tempDir,
+        ".knowledge",
+        "docsets",
+        "uninitialized-docs",
+      );
+      await fs.mkdir(docsetDir, { recursive: true });
+
+      // Try to search the uninitialized docset
+      const callToolHandler = (server as any)._requestHandlers.get(
+        "tools/call",
+      );
+      expect(callToolHandler).toBeDefined();
+
+      const result = await callToolHandler({
+        method: "tools/call",
+        params: {
+          name: "search_docs",
+          arguments: {
+            docset_id: "uninitialized-docs",
+            keywords: "test",
+          },
+        },
+      });
+
+      // Should return an error
+      expect(result.isError).toBe(true);
+      expect(result.content[0].text).toContain("not initialized");
+      expect(result.content[0].text).toContain("agentic-knowledge init");
+    });
   });
 });
diff --git a/packages/mcp-server/src/__tests__/web-sources.test.ts b/packages/mcp-server/src/__tests__/web-sources.test.ts
index 57feeee..52b1b97 100644
--- a/packages/mcp-server/src/__tests__/web-sources.test.ts
+++ b/packages/mcp-server/src/__tests__/web-sources.test.ts
@@ -55,6 +55,19 @@ template: "Search for '{{keywords}}' in {{local_path}}. Also consider: {{general
       "# Test Documentation\n\nThis simulates downloaded web content.",
     );
 
+    // Create metadata file (simulating what init command creates)
+    const metadata = {
+      docset_id: "web-source-docs",
+      docset_name: "Web Source Documentation",
+      initialized_at: new Date().toISOString(),
+      total_files: 1,
+      sources_count: 1,
+    };
+    await fs.writeFile(
+      join(webSourceDir, ".agentic-metadata.json"),
+      JSON.stringify(metadata, null, 2),
+    );
+
     // Mock process.cwd to return our temp directory
     vi.spyOn(process, "cwd").mockReturnValue(tempDir);
 
diff --git a/packages/mcp-server/src/server.ts b/packages/mcp-server/src/server.ts
index 83cf08b..e4a4421 100644
--- a/packages/mcp-server/src/server.ts
+++ b/packages/mcp-server/src/server.ts
@@ -18,6 +18,8 @@ import {
   createStructuredResponse,
   type KnowledgeConfig,
 } from "@codemcp/knowledge-core";
+import { existsSync } from "node:fs";
+import { resolve, dirname } from "node:path";
 
 /**
  * Create an agentic knowledge MCP server
@@ -43,12 +45,12 @@ export function createAgenticKnowledgeServer() {
   const CONFIG_CACHE_TTL = 60000; // 1 minute cache
 
   /**
-   * Load configuration with caching
+   * Load configuration with caching (returns null if no config found)
    */
   async function getConfiguration(): Promise<{
     config: KnowledgeConfig;
     configPath: string;
-  }> {
+  } | null> {
     const now = Date.now();
     if (configCache && now - configLoadTime < CONFIG_CACHE_TTL) {
       return configCache;
@@ -58,9 +60,7 @@ export function createAgenticKnowledgeServer() {
       // Find configuration file path
       const configPath = await findConfigPath();
       if (!configPath) {
-        throw new Error(
-          "No configuration file found. Please create a .knowledge/config.yaml file in your project.",
-        );
+        return null; // No config file found - server can still start
       }
 
       // Load configuration
@@ -74,62 +74,75 @@ export function createAgenticKnowledgeServer() {
       // Clear cache on error to force retry next time
       configCache = null;
       configLoadTime = 0;
-      throw error;
+      // Return null instead of throwing - allow server to start
+      console.error("Error loading configuration:", error);
+      return null;
     }
   }
 
   // Register tool handlers
   server.setRequestHandler(ListToolsRequestSchema, async () => {
-    try {
-      // Load configuration to get available docsets
-      const { config } = await getConfiguration();
-
-      // Build rich description with available docsets
-      const docsetInfo = config.docsets
-        .map((docset) => {
-          const description = docset.description
-            ? ` - ${docset.description}`
-            : "";
-          return `• **${docset.id}** (${docset.name})${description}`;
-        })
-        .join("\n");
-
-      const searchDocsDescription = `Search for documentation in available docsets. Returns structured response with search instructions and parameters.
-
-📚 **AVAILABLE DOCSETS:**
-${docsetInfo}
-
-🔍 **STRUCTURED RESPONSE:**
-Returns JSON object with:
-- instructions: Search guidance text
-- search_terms: Primary keywords to search for
-- generalized_search_terms: Broader terms for context
-- path: Local directory path to search in
-
-Use the path and search terms with your text search tools (grep, rg, ripgrep, find).`;
+    // Load configuration to get available docsets
+    const configData = await getConfiguration();
 
+    // If no configuration, return tools with setup instructions
+    if (!configData) {
       return {
         tools: [
           {
             name: "search_docs",
-            description: searchDocsDescription,
+            description: `Search for documentation in configured docsets. Returns structured response with search instructions and parameters.
+
+⚠️ **NO DOCSETS CONFIGURED**
+
+To configure docsets and use this tool:
+
+**Option 1: Use CLI (recommended)**
+\`\`\`bash
+# Create a docset for a Git repository
+agentic-knowledge create \\
+  --preset git-repo \\
+  --id my-docs \\
+  --name "My Documentation" \\
+  --url https://github.com/user/repo.git
+
+# Initialize it (downloads the docs)
+agentic-knowledge init my-docs
+
+# Restart the MCP server
+agentic-knowledge
+\`\`\`
+
+**Option 2: Manual configuration**
+Create \`.knowledge/config.yaml\`:
+\`\`\`yaml
+version: "1.0"
+docsets:
+  - id: my-docs
+    name: My Documentation
+    sources:
+      - type: local_folder
+        paths: ["./docs"]
+\`\`\`
+
+After configuring, the tool will show available docsets here.`,
             inputSchema: {
               type: "object",
               properties: {
                 docset_id: {
                   type: "string",
-                  description: "Choose the docset to search in.",
-                  enum: config.docsets.map((d) => d.id),
+                  description:
+                    "The identifier of the docset to search in. (No docsets configured - see tool description for setup instructions)",
                 },
                 keywords: {
                   type: "string",
                   description:
-                    'Primary search terms or concepts you\'re looking for. Be specific about what you want to find (e.g., "authentication middleware", "user validation", "API rate limiting"). Include the exact terms you expect to appear in the documentation.',
+                    'Primary search terms or concepts you\'re looking for. Be specific about what you want to find (e.g., "authentication middleware", "user validation", "API rate limiting").',
                 },
                 generalized_keywords: {
                   type: "string",
                   description:
-                    'Related terms, synonyms, or contextual keywords that may appear alongside your primary keywords but are not your main target. These help broaden the search context and catch relevant content that might use different terminology (e.g., for "authentication" you might include "login, signin, oauth, credentials, tokens"). Think of terms that would appear in the same sections or discussions as your main keywords.',
+                    "Related terms, synonyms, or contextual keywords that may appear alongside your primary keywords but are not your main target.",
                 },
               },
               required: ["docset_id", "keywords"],
@@ -139,7 +152,7 @@ Use the path and search terms with your text search tools (grep, rg, ripgrep, fi
           {
             name: "list_docsets",
             description:
-              "List all available documentation sets (docsets) with detailed information. Note: The search_docs tool already shows available docsets in its description, so this tool is mainly for getting additional metadata.",
+              "List all available documentation sets (docsets) with detailed information. (Currently no docsets configured - see search_docs description for setup instructions)",
             inputSchema: {
               type: "object",
               properties: {},
@@ -148,50 +161,73 @@ Use the path and search terms with your text search tools (grep, rg, ripgrep, fi
           },
         ],
       };
-    } catch (error) {
-      // Fallback to basic tools if configuration fails
-      return {
-        tools: [
-          {
-            name: "search_docs",
-            description:
-              "Search for documentation guidance based on keywords and context. Returns intelligent navigation instructions to help you find relevant information in a specific docset. (Configuration error - use list_docsets to see available options)",
-            inputSchema: {
-              type: "object",
-              properties: {
-                docset_id: {
-                  type: "string",
-                  description:
-                    "The identifier of the docset to search in. Use list_docsets to see available options.",
-                },
-                keywords: {
-                  type: "string",
-                  description:
-                    'Primary search terms or concepts you\'re looking for. Be specific about what you want to find (e.g., "authentication middleware", "user validation", "API rate limiting"). Include the exact terms you expect to appear in the documentation.',
-                },
-                generalized_keywords: {
-                  type: "string",
-                  description:
-                    'Related terms, synonyms, or contextual keywords that may appear alongside your primary keywords but are not your main target. These help broaden the search context and catch relevant content that might use different terminology (e.g., for "authentication" you might include "login, signin, oauth, credentials, tokens"). Think of terms that would appear in the same sections or discussions as your main keywords.',
-                },
+    }
+
+    // Configuration exists - build rich description with available docsets
+    const { config } = configData;
+    const docsetInfo = config.docsets
+      .map((docset) => {
+        const description = docset.description
+          ? ` - ${docset.description}`
+          : "";
+        return `• **${docset.id}** (${docset.name})${description}`;
+      })
+      .join("\n");
+
+    const searchDocsDescription = `Search for documentation in available docsets. Returns structured response with search instructions and parameters.
+
+📚 **AVAILABLE DOCSETS:**
+${docsetInfo}
+
+🔍 **STRUCTURED RESPONSE:**
+Returns JSON object with:
+- instructions: Search guidance text
+- search_terms: Primary keywords to search for
+- generalized_search_terms: Broader terms for context
+- path: Local directory path to search in
+
+Use the path and search terms with your text search tools (grep, rg, ripgrep, find).`;
+
+    return {
+      tools: [
+        {
+          name: "search_docs",
+          description: searchDocsDescription,
+          inputSchema: {
+            type: "object",
+            properties: {
+              docset_id: {
+                type: "string",
+                description: "Choose the docset to search in.",
+                enum: config.docsets.map((d) => d.id),
+              },
+              keywords: {
+                type: "string",
+                description:
+                  'Primary search terms or concepts you\'re looking for. Be specific about what you want to find (e.g., "authentication middleware", "user validation", "API rate limiting"). Include the exact terms you expect to appear in the documentation.',
+              },
+              generalized_keywords: {
+                type: "string",
+                description:
+                  'Related terms, synonyms, or contextual keywords that may appear alongside your primary keywords but are not your main target. These help broaden the search context and catch relevant content that might use different terminology (e.g., for "authentication" you might include "login, signin, oauth, credentials, tokens"). Think of terms that would appear in the same sections or discussions as your main keywords.',
               },
-              required: ["docset_id", "keywords"],
-              additionalProperties: false,
             },
+            required: ["docset_id", "keywords"],
+            additionalProperties: false,
           },
-          {
-            name: "list_docsets",
-            description:
-              "List all available documentation sets (docsets) that can be searched. Each docset represents a specific project, library, or knowledge base.",
-            inputSchema: {
-              type: "object",
-              properties: {},
-              additionalProperties: false,
-            },
+        },
+        {
+          name: "list_docsets",
+          description:
+            "List all available documentation sets (docsets) with detailed information. Note: The search_docs tool already shows available docsets in its description, so this tool is mainly for getting additional metadata.",
+          inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false,
           },
-        ],
-      };
-    }
+        },
+      ],
+    };
   });
 
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -215,20 +251,62 @@ Use the path and search terms with your text search tools (grep, rg, ripgrep, fi
           }
 
           // Load configuration
-          const { config, configPath } = await getConfiguration();
+          const configData = await getConfiguration();
+          if (!configData) {
+            throw new Error(
+              "No configuration file found.\n\n" +
+                "To configure docsets:\n\n" +
+                "**Option 1: Use CLI (recommended)**\n" +
+                'agentic-knowledge create --preset git-repo --id my-docs --name "My Docs" --url <repo-url>\n' +
+                "agentic-knowledge init my-docs\n\n" +
+                "**Option 2: Manual configuration**\n" +
+                "Create .knowledge/config.yaml in your project root.\n" +
+                "See the search_docs tool description for example configuration.",
+            );
+          }
+
+          const { config, configPath } = configData;
 
           // Find the requested docset
           const docset = config.docsets.find((d) => d.id === docset_id);
           if (!docset) {
             const availableIds = config.docsets.map((d) => d.id).join(", ");
             throw new Error(
-              `Docset '${docset_id}' not found. Available docsets: ${availableIds}`,
+              `Docset '${docset_id}' not found.\n\n` +
+                `Available docsets: ${availableIds}\n\n` +
+                `To create a new docset:\n` +
+                `agentic-knowledge create --preset git-repo --id ${docset_id} --name "My Docs" --url <repo-url>\n` +
+                `agentic-knowledge init ${docset_id}`,
             );
           }
 
           // Calculate local path
           const localPath = calculateLocalPath(docset, configPath);
 
+          // Check if docset is initialized by checking for metadata file
+          const primarySource = docset.sources?.[0];
+          if (primarySource?.type === "git_repo") {
+            // For git repos, check if .agentic-metadata.json exists
+            const configDir = dirname(configPath);
+            const projectRoot = dirname(configDir);
+            const absolutePath = resolve(projectRoot, localPath);
+            const metadataPath = resolve(
+              absolutePath,
+              ".agentic-metadata.json",
+            );
+
+            if (!existsSync(metadataPath)) {
+              throw new Error(
+                `Docset '${docset_id}' is not initialized.\n\n` +
+                  `The docset is configured but hasn't been initialized yet.\n\n` +
+                  `To initialize this docset:\n` +
+                  `agentic-knowledge init ${docset_id}\n\n` +
+                  `To check status of all docsets:\n` +
+                  `agentic-knowledge status`,
+              );
+            }
+          }
+
           // Create template context with proper function signature
           const templateContext = createTemplateContext(
             localPath,
@@ -262,7 +340,37 @@ Use the path and search terms with your text search tools (grep, rg, ripgrep, fi
 
         case "list_docsets": {
           // Load configuration
-          const { config, configPath } = await getConfiguration();
+          const configData = await getConfiguration();
+          if (!configData) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text:
+                    "No docsets configured.\n\n" +
+                    "To configure docsets:\n\n" +
+                    "**Option 1: Use CLI (recommended)**\n" +
+                    "```bash\n" +
+                    'agentic-knowledge create --preset git-repo --id my-docs --name "My Docs" --url <repo-url>\n' +
+                    "agentic-knowledge init my-docs\n" +
+                    "```\n\n" +
+                    "**Option 2: Manual configuration**\n" +
+                    "Create `.knowledge/config.yaml`:\n" +
+                    "```yaml\n" +
+                    'version: "1.0"\n' +
+                    "docsets:\n" +
+                    "  - id: my-docs\n" +
+                    "    name: My Documentation\n" +
+                    "    sources:\n" +
+                    "      - type: local_folder\n" +
+                    '        paths: ["./docs"]\n' +
+                    "```",
+                },
+              ],
+            };
+          }
+
+          const { config, configPath } = configData;
 
           // Return list of available docsets with calculated paths
           const docsets = await Promise.all(