Add virtual environment setup and minimal dependencies (#149)

## Changes
- Add virtual environment setup instructions to all docs
- Create requirements.txt with minimal dependencies (13 packages)
- Make anthropic optional (only needed for API enhancement)
- Clarify path notation (~ = $HOME, /Users/yourname examples)
- Add venv activation reminders throughout documentation

## Files Changed
- README.md: Added venv setup section to CLI method
- BULLETPROOF_QUICKSTART.md: Replaced Step 4 with venv setup
- CLAUDE.md: Updated Prerequisites with venv instructions
- requirements.txt: Created with minimal deps (requests, beautifulsoup4, pytest)

## Why
- Prevents package conflicts and permission issues
- Standard Python development practice
- Enables proper pytest usage without pipx complications
- Makes setup clearer for beginners

BULLETPROOF_QUICKSTART.md

@@ -117,6 +117,7 @@ git --version
 
 Pick a location for the project. Good choices:
 - macOS/Linux: `~/Projects/` or `~/Documents/`
+  - Note: `~` means your home directory (`$HOME` or `/Users/yourname` on macOS, `/home/yourname` on Linux)
 - Windows: `C:\Users\YourName\Projects\`
 
 ### Clone the Repository
@@ -143,7 +144,10 @@ remote: Counting objects: 100% (245/245), done.
 **Verify you're in the right place:**
 ```bash
 pwd
-# Should show: /Users/yourname/Projects/Skill_Seekers (or similar)
+# Should show something like:
+#   macOS: /Users/yourname/Projects/Skill_Seekers
+#   Linux: /home/yourname/Projects/Skill_Seekers
+# (Replace 'yourname' with YOUR actual username)
 
 ls
 # Should show: README.md, cli/, mcp/, configs/, etc.
@@ -161,31 +165,67 @@ ping google.com
 
 ---
 
-## Step 4: Install Dependencies (2 minutes)
+## Step 4: Setup Virtual Environment & Install Dependencies (3 minutes)
+
+A virtual environment keeps Skill Seeker's dependencies isolated and prevents conflicts.
 
 ```bash
 # Make sure you're in the Skill_Seekers directory
-cd ~/Projects/Skill_Seekers  # Adjust path if you chose different location
+cd ~/Projects/Skill_Seekers  # ~ means your home directory ($HOME)
+                             # Adjust if you chose a different location
 
-# Install required packages
-pip3 install requests beautifulsoup4
+# Create virtual environment
+python3 -m venv venv
+
+# Activate it
+source venv/bin/activate  # macOS/Linux
+# Windows users: venv\Scripts\activate
 ```
 
 **✅ Success looks like:**
 ```
-Successfully installed requests-2.31.0 beautifulsoup4-4.12.3
+(venv) username@computer Skill_Seekers %
+```
+Notice `(venv)` appears in your prompt - this means the virtual environment is active!
+
+```bash
+# Now install packages (only needed once)
+pip install requests beautifulsoup4 pytest
+
+# Save the dependency list
+pip freeze > requirements.txt
 ```
 
-**❌ If pip3 not found:**
+**✅ Success looks like:**
+```
+Successfully installed requests-2.32.5 beautifulsoup4-4.14.2 pytest-8.4.2 ...
+```
+
+**Optional - Only if you want API-based enhancement (not needed for LOCAL enhancement):**
+```bash
+pip install anthropic
+```
+
+**Important Notes:**
+- **Every time** you open a new terminal to use Skill Seeker, run `source venv/bin/activate` first
+- You'll know it's active when you see `(venv)` in your terminal prompt
+- To deactivate later: just type `deactivate`
+
+**❌ If python3 not found:**
 ```bash
 # Try without the 3
-pip install requests beautifulsoup4
+python -m venv venv
 ```
 
 **❌ If permission denied:**
 ```bash
-# Add --user flag
-pip3 install --user requests beautifulsoup4
+# Virtual environment approach doesn't need sudo - you might have the wrong path
+# Make sure you're in the Skill_Seekers directory:
+pwd
+# Should show something like:
+#   macOS: /Users/yourname/Projects/Skill_Seekers
+#   Linux: /home/yourname/Projects/Skill_Seekers
+# (Replace 'yourname' with YOUR actual username)
 ```
 
 ---

CLAUDE.md

@@ -58,14 +58,35 @@ Skill Seeker automatically converts any documentation website into a Claude AI s
 
 **Python Version:** Python 3.10 or higher (required for MCP integration)
 
-**Required Dependencies:**
+**Setup with Virtual Environment (Recommended):**
 ```bash
-pip3 install requests beautifulsoup4
+# One-time setup
+python3 -m venv venv
+source venv/bin/activate  # macOS/Linux (Windows: venv\Scripts\activate)
+pip install requests beautifulsoup4 pytest
+pip freeze > requirements.txt
+
+# Every time you use Skill Seeker in a new terminal session
+source venv/bin/activate  # Activate before using any commands
+```
+
+**Why use a virtual environment?**
+- Keeps dependencies isolated from system Python
+- Prevents package version conflicts
+- Standard Python development practice
+- Required for running tests with pytest
+
+**If someone else clones this repo:**
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
 ```
 
 **Optional (for API-based enhancement):**
 ```bash
-pip3 install anthropic
+source venv/bin/activate
+pip install anthropic
 export ANTHROPIC_API_KEY=sk-ant-...
 ```
 

README.md

@@ -149,11 +149,40 @@ Package skill at output/react/
 
 ### Method 2: CLI (Traditional)
 
+#### One-Time Setup: Create Virtual Environment
+
+```bash
+# Clone repository
+git clone https://github.com/yusufkaraaslan/Skill_Seekers.git
+cd Skill_Seekers
+
+# Create virtual environment
+python3 -m venv venv
+
+# Activate virtual environment
+source venv/bin/activate  # macOS/Linux
+# OR on Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install requests beautifulsoup4 pytest
+
+# Save dependencies
+pip freeze > requirements.txt
+
+# Optional: Install anthropic for API-based enhancement (not needed for LOCAL enhancement)
+# pip install anthropic
+```
+
+**Always activate the virtual environment before using Skill Seeker:**
+```bash
+source venv/bin/activate  # Run this each time you start a new terminal session
+```
+
 #### Easiest: Use a Preset
 
 ```bash
-# Install dependencies (macOS)
-pip3 install requests beautifulsoup4
+# Make sure venv is activated (you should see (venv) in your prompt)
+source venv/bin/activate
 
 # Optional: Estimate pages first (fast, 1-2 minutes)
 python3 cli/estimate_pages.py configs/godot.json

requirements.txt

@@ -0,0 +1,13 @@
+beautifulsoup4==4.14.2
+certifi==2025.10.5
+charset-normalizer==3.4.4
+idna==3.11
+iniconfig==2.3.0
+packaging==25.0
+pluggy==1.6.0
+Pygments==2.19.2
+pytest==8.4.2
+requests==2.32.5
+soupsieve==2.8
+typing_extensions==4.15.0
+urllib3==2.5.0