CHORE: updated readme & gitignore

.gitignore

@@ -52,6 +52,8 @@ htmlcov/
 *.swp
 *.swo
 *~
+.cursorindexingignore
+.specstory/
 
 # Claude Code
 CLAUDE.md

README.md

@@ -31,7 +31,89 @@ A terminal application that enables two LLMs to engage in structured debates on
 - OpenRouter API key (if using OpenRouter) - Get one at [openrouter.ai](https://openrouter.ai/keys)
 - LMStudio running locally (if using LMStudio) - Download at [lmstudio.ai](https://lmstudio.ai/)
 
-## Installation
+## Quick Start Guide (For Beginners)
+
+**New to coding?** Follow these simple steps to get your debate running in 5 minutes:
+
+### Step 1: Get an API Key
+1. Go to [openrouter.ai/keys](https://openrouter.ai/keys)
+2. Sign up for a free account
+3. Click "Create Key" and copy your API key (it looks like `sk-or-v1-...`)
+4. Keep this somewhere safe - you'll need it in a moment!
+
+### Step 2: Download and Set Up
+1. Download this project (green "Code" button → "Download ZIP")
+2. Unzip the folder anywhere on your computer
+3. Open Terminal (Mac/Linux) or Command Prompt (Windows)
+4. Navigate to the folder:
+   ```bash
+   cd path/to/debate-bots
+   ```
+
+### Step 3: Install Python Dependencies
+
+**Option A - Easy Way (Mac/Linux):**
+Just run the included setup script:
+```bash
+chmod +x run.sh
+./run.sh
+```
+*This will automatically install everything and start the app!*
+
+**Option B - Manual Way (All platforms):**
+Run this command:
+```bash
+pip install -r requirements.txt
+```
+*This installs all the necessary software the app needs.*
+
+**Note:** If you used Option A, skip to Step 4 - the script will ask you for setup details!
+
+### Step 4: Configure Your API Key
+The easiest way:
+1. Create a file called `.env` in the debate-bots folder
+2. Open it with any text editor (Notepad, TextEdit, etc.)
+3. Add this line, replacing with your actual key:
+   ```
+   OPENROUTER_API_KEY=sk-or-v1-your-key-here
+   ```
+4. Save the file
+
+### Step 5: Create Your Configuration
+1. Copy the file `config.example.yaml`
+2. Rename the copy to `config.yaml`
+3. Open `config.yaml` in a text editor
+4. You'll see two agents - you can leave them as-is or change the models/prompts
+5. Save the file (no need to add your API key here - it's already in `.env`!)
+
+### Step 6: Start Your First Debate!
+
+**Mac/Linux users:**
+```bash
+./run.sh
+```
+
+**Windows users (or if you prefer):**
+```bash
+python -m src.main
+```
+
+The app will ask you:
+- **What topic to debate?** (e.g., "Pineapple belongs on pizza")
+- After each round, you can continue, give instructions, or quit
+
+That's it! You'll see the two AI agents debate in real-time. 🎉
+
+### Common Issues
+- **"Command not found"**: Make sure Python is installed. Try `python3` instead of `python`, or use `./run.sh` on Mac/Linux
+- **"No module named..."**: Run `pip install -r requirements.txt` again, or just use `./run.sh` which handles this automatically
+- **"Permission denied" for run.sh**: Run `chmod +x run.sh` first to make it executable
+- **"API key invalid"**: Double-check you copied the full key from OpenRouter into `.env`
+- **Nothing streams**: That's okay! The debate still works, just disable streaming with `--no-streaming`
+
+---
+
+## Detailed Installation (For Advanced Users)
 
 1. Clone or download this repository:
 ```bash