From e5b27ff1e577ff6a83262ee9b48077d2b13eab40 Mon Sep 17 00:00:00 2001
From: Sam Valladares <samvalladares21@gmail.com>
Date: Mon, 26 Jan 2026 22:34:10 -0600
Subject: [PATCH] docs: fix README installation and cache documentation

- Add -s user flag to claude mcp add commands for user scope install
- Correct fastembed cache location docs (.fastembed_cache in CWD, not ~/.cache/huggingface)
- Add troubleshooting section for .fastembed_cache folder in project directories
- Include FASTEMBED_CACHE_PATH env var workaround

Fixes issues reported by Reddit user feedback.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 README.md | 37 ++++++++++++++++++++++++++++++-------
 1 file changed, 30 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 7157cba..3f1e02e 100644
--- a/README.md
+++ b/README.md
@@ -87,7 +87,8 @@ export PATH="$PATH:/path/to/vestige/target/release"
 
 **Option A: One-liner (Recommended)**
 ```bash
-claude mcp add vestige vestige-mcp
+# User scope (works across all projects)
+claude mcp add vestige vestige-mcp -s user
 ```
 
 **Option B: Manual Config**
@@ -160,9 +161,20 @@ Vestige downloads the **Nomic Embed Text v1.5** model (~130MB) from Hugging Face
 
 **All subsequent runs are fully offline.**
 
-Model cache location:
-- macOS/Linux: `~/.cache/huggingface/`
-- Windows: `%USERPROFILE%\.cache\huggingface\`
+Model cache location (fastembed):
+- Creates `.fastembed_cache/` in the **current working directory** on first run
+- Contains symlinks to model files in `~/.cache/huggingface/`
+
+**Recommended**: Run your first Vestige command from your home directory to create the cache there:
+```bash
+cd ~
+vestige health   # Creates ~/.fastembed_cache/ once
+```
+
+Or set the environment variable to control cache location:
+```bash
+export FASTEMBED_CACHE_PATH="$HOME/.fastembed_cache"
+```
 
 ### Data Storage & Backup
 
@@ -345,7 +357,7 @@ One shared memory for all projects. Good for:
 
 ```bash
 # Default behavior - no configuration needed
-claude mcp add vestige vestige-mcp
+claude mcp add vestige vestige-mcp -s user
 ```
 
 Database location: `~/Library/Application Support/com.vestige.core/vestige.db`
@@ -1389,10 +1401,21 @@ which vestige-mcp
 
 If not found:
 ```bash
-# Use full path in Claude config
-claude mcp add vestige /full/path/to/vestige-mcp
+# Use full path in Claude config (with -s user for global access)
+claude mcp add vestige /full/path/to/vestige-mcp -s user
 ```
 
+### `.fastembed_cache` folder appearing in project directories
+
+This folder is created by the fastembed library on first run, in whatever directory you're in. **This is a known issue.**
+
+**Solutions:**
+1. **Run first command from home**: `cd ~ && vestige health` (creates cache there once)
+2. **Set cache path**: `export FASTEMBED_CACHE_PATH="$HOME/.fastembed_cache"`
+3. **Add to `.gitignore`**: The folder is already in Vestige's `.gitignore` template
+
+The cache contains model files (~130MB) and symlinks. Once created, it's reused for all future runs.
+
 ### Model download fails
 
 First run requires internet to download the embedding model. If behind a proxy: