From de5344caf97cab13366db4af78b311d1ffa06db4 Mon Sep 17 00:00:00 2001
From: Preston Brown <7024735+prestonbrown@users.noreply.github.com>
Date: Wed, 22 Oct 2025 14:54:05 -0400
Subject: [PATCH] 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 | 60 ++++++++++++++++++++++++++++++++-------
 CLAUDE.md                 | 27 ++++++++++++++++--
 README.md                 | 33 +++++++++++++++++++--
 requirements.txt          | 13 +++++++++
 4 files changed, 118 insertions(+), 15 deletions(-)
 create mode 100644 requirements.txt

diff --git a/BULLETPROOF_QUICKSTART.md b/BULLETPROOF_QUICKSTART.md
index f7a1b1e..6d4a0e5 100644
--- a/BULLETPROOF_QUICKSTART.md
+++ b/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)
 ```
 
 ---
diff --git a/CLAUDE.md b/CLAUDE.md
index 83b45f5..fa40031 100644
--- a/CLAUDE.md
+++ b/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-...
 ```
 
diff --git a/README.md b/README.md
index 02d65ed..745e805 100644
--- a/README.md
+++ b/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
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000..f764ad0
--- /dev/null
+++ b/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