diff --git a/USER_MANUAL.md b/USER_MANUAL.md
new file mode 100644
index 0000000..4f142e1
--- /dev/null
+++ b/USER_MANUAL.md
@@ -0,0 +1,364 @@
+# Companion AI - User Manual
+
+A practical guide to running and using your personal AI companion.
+
+---
+
+## Quick Start (5 minutes)
+
+### Option 1: Docker (Recommended)
+
+```bash
+# 1. Clone and enter directory
+git clone https://github.com/santhoshjan/companion.git
+cd companion
+
+# 2. Edit config.json - set your vault path
+nano config.json
+# Change: "path": "/home/yourname/KnowledgeVault/Default"
+
+# 3. Start everything
+docker-compose up -d
+
+# 4. Open the UI
+open http://localhost:5173
+```
+
+### Option 2: Manual Install
+
+```bash
+# Install dependencies
+pip install -e ".[dev]"
+
+# Run the API
+python -m uvicorn companion.api:app --host 0.0.0.0 --port 7373
+```
+
+---
+
+## Configuration
+
+Before first use, edit `config.json`:
+
+```json
+{
+  "vault": {
+    "path": "/path/to/your/obsidian/vault"
+  }
+}
+```
+
+**Required paths to set:**
+- `vault.path` - Your Obsidian vault directory
+- `rag.vector_store.path` - Where to store embeddings (default: `~/.companion/vectors`)
+- `companion.memory.persistent_store` - Conversation history (default: `~/.companion/memory.db`)
+
+---
+
+## Indexing Your Vault
+
+The system needs to index your vault before it can answer questions.
+
+### One-time Full Index
+
+```bash
+# Using Python module
+python -m companion.indexer_daemon.cli index
+
+# Or with Docker
+docker-compose exec companion-api python -m companion.indexer_daemon.cli index
+```
+
+**Output:**
+```
+Running full index...
+Done. Total chunks: 12,847
+```
+
+### Continuous File Watching
+
+```bash
+# Auto-sync when files change
+python -m companion.indexer_daemon.watcher
+```
+
+**What it does:**
+- Monitors your vault for changes
+- Automatically re-indexes modified files
+- Debounced (5-second delay to batch rapid changes)
+
+### Check Index Status
+
+```bash
+python -m companion.indexer_daemon.cli status
+```
+
+**Output:**
+```
+Total chunks: 12,847
+Indexed files: 847
+Unindexed files: 3
+```
+
+### Incremental Sync
+
+```bash
+# Sync only changed files
+python -m companion.indexer_daemon.cli sync
+```
+
+**When to use:**
+- After editing a few notes
+- Faster than full re-index
+- Keeps vector store updated
+
+---
+
+## Using the Chat Interface
+
+### Web UI
+
+1. Start the backend: `python -m uvicorn companion.api:app --port 7373`
+2. In another terminal: `cd ui && npm run dev`
+3. Open http://localhost:5173
+
+**Interface:**
+- Type messages in the bottom textarea
+- Press Enter to send
+- Citations appear in a side panel when RAG retrieves context
+- Conversation history persists per session
+
+### API Directly
+
+```bash
+# Start a conversation
+curl -X POST http://localhost:7373/chat \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "What did I write about my trip to Japan?",
+    "stream": true
+  }'
+```
+
+**Parameters:**
+- `message` (required): Your question
+- `session_id` (optional): Continue existing conversation
+- `stream` (optional): Stream response (default: true)
+- `use_rag` (optional): Enable vault search (default: true)
+
+### Get Session History
+
+```bash
+curl http://localhost:7373/sessions/{session_id}/history
+```
+
+---
+
+## Fine-Tuning (Optional)
+
+### Extract Training Data
+
+```bash
+# Extract reflection examples from your vault
+python -m companion.forge.extract \
+  --output training_data.jsonl \
+  --min-length 100
+```
+
+### Train Model
+
+```bash
+# Start training (takes hours, needs GPU)
+python -m companion.forge.train \
+  --data training_data.jsonl \
+  --output-dir ./models
+```
+
+### Export to GGUF
+
+```bash
+# Convert for llama.cpp inference
+python -m companion.forge.export \
+  --model ./models/checkpoint \
+  --output companion-7b.gguf
+```
+
+### Reload Model (Hot Swap)
+
+```bash
+# Admin endpoint - reload without restarting API
+curl -X POST http://localhost:7373/admin/reload-model \
+  -H "Content-Type: application/json" \
+  -d '{"model_path": "/path/to/companion-7b.gguf"}'
+```
+
+---
+
+## Command Reference
+
+### Indexer Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `index` | Full re-index of vault | `cli index` |
+| `sync` | Incremental sync | `cli sync` |
+| `reindex` | Force full reindex | `cli reindex` |
+| `status` | Show index statistics | `cli status` |
+
+### Common Options
+
+All indexer commands support:
+- `--config PATH` : Use alternative config file
+- `--verbose` : Detailed logging
+
+### Environment Variables
+
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `COMPANION_CONFIG` | Config file path | `/etc/companion/config.json` |
+| `COMPANION_DATA_DIR` | Data storage root | `/var/lib/companion` |
+| `VAULT_PATH` | Override vault location | `/home/user/vault` |
+
+---
+
+## Troubleshooting
+
+### "No module named 'companion'"
+
+```bash
+# Install in editable mode
+pip install -e "."
+
+# Or set PYTHONPATH
+export PYTHONPATH=/path/to/companion:$PYTHONPATH
+```
+
+### "Failed to generate embedding"
+
+- Check Ollama is running: `curl http://localhost:11434/api/tags`
+- Verify embedding model is pulled: `ollama pull mxbai-embed-large`
+- Check `config.json` has correct `rag.embedding.base_url`
+
+### "No results from search"
+
+1. Check index status: `cli status`
+2. Verify vault path is correct in config
+3. Run full index: `cli index`
+4. Check file patterns match your notes (default: `*.md`)
+
+### "Port 7373 already in use"
+
+```bash
+# Find and kill process
+lsof -i :7373
+kill <PID>
+
+# Or use different port
+python -m uvicorn companion.api:app --port 7374
+```
+
+### Windows: Scripts won't run
+
+```powershell
+# Set execution policy
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+
+# Or run with explicit bypass
+powershell -ExecutionPolicy Bypass -File scripts/install.ps1
+```
+
+---
+
+## Systemd Commands (Linux)
+
+If installed as a service:
+
+```bash
+# Start/stop/restart
+sudo systemctl start companion-api
+sudo systemctl stop companion-api
+sudo systemctl restart companion-api
+
+# Check status
+sudo systemctl status companion-api
+
+# View logs
+sudo journalctl -u companion-api -f
+
+# Enable auto-start
+sudo systemctl enable companion-api
+```
+
+---
+
+## Docker Commands
+
+```bash
+# Start all services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f companion-api
+
+# Run indexer command
+docker-compose exec companion-api python -m companion.indexer_daemon.cli index
+
+# Rebuild after code changes
+docker-compose up -d --build
+
+# Stop everything
+docker-compose down
+```
+
+---
+
+## Performance Tips
+
+### Indexing Large Vaults
+
+- First index takes time (1-5 hours for 1000+ notes)
+- Subsequent syncs are fast (seconds to minutes)
+- Use `sync` instead of `reindex` for updates
+
+### Memory Usage
+
+- API server: ~500MB-1GB RAM
+- Indexer: ~200MB while watching
+- LanceDB is disk-based, scales to 100K+ chunks
+
+### GPU Acceleration
+
+For fine-tuning (not required for RAG):
+- Requires CUDA-capable GPU
+- Install `unsloth` and `torch` with CUDA support
+- Training uses ~10GB VRAM for 7B models
+
+---
+
+## Best Practices
+
+1. **Index regularly**: Run `sync` daily or use the file watcher
+2. **Back up vectors**: Copy `~/.companion/vectors.lance` periodically
+3. **Use session IDs**: Pass `session_id` to maintain conversation context
+4. **Monitor citations**: Check the sources panel to verify RAG is working
+5. **Keep Ollama running**: The embedding service must be available
+
+---
+
+## Getting Help
+
+- Check logs: `journalctl -u companion-api` or `docker-compose logs`
+- Verify config: `python -c "from companion.config import load_config; print(load_config())"`
+- Test search directly: `python -m companion.indexer_daemon.cli search "test query"`
+
+---
+
+## Next Steps
+
+1. Index your vault
+2. Start the API server
+3. Open the web UI
+4. Ask your first question
+5. Explore the citations
+
+Enjoy your personal AI companion!
\ No newline at end of file