# negoT8 — Setup Guide

## Why it works on my machine but not yours

The most common causes are listed here. Go through them **in order**.

---

## 1. `.env` file is missing ❌

`.env` is **never committed to Git** (it's in `.gitignore`).  
Your friend must create it manually:

```bash
cp .env.example .env
# then open .env and fill in every value
```

Every blank/missing key will silently cause failures — Telegram bots won't start, AI won't respond, blockchain calls will fail.

---

## 2. Python version mismatch ⚠️

This project requires **Python 3.10+** (3.9 works but shows deprecation warnings from Google libraries).

```bash
python3 --version    # must be 3.10 or higher recommended
```

If on macOS and Python is too old:
```bash
brew install python@3.11
```

---

## 3. Virtual environment not created / activated ❌

The project uses a `venv` that is **not committed to Git**.  
Your friend must create and activate it:

```bash
# In the repo root
python3 -m venv venv

# macOS / Linux
source venv/bin/activate

# Windows
venv\Scripts\activate
```

---

## 4. Dependencies not installed ❌

After activating the venv:

```bash
pip install -r requirements.txt
```

If `requirements.txt` was missing before, it's now at the repo root.

---

## 5. Bot tokens: only ONE process can poll at a time 🔑

Each Telegram bot token can only be used by **one running process** at a time.  
If your machine is already running the bots, your friend's machine will get:

```
telegram.error.Conflict: terminated by other getUpdates request
```

**Fix**: Stop the bots on your machine before your friend starts them.  
Each person needs their **own BotFather tokens** for their own copy.

---

## 6. `MOCK_MODE` must be set correctly

In `.env`:
- `MOCK_MODE=true` → no Gemini/AI calls, uses hardcoded responses (safe for testing)
- `MOCK_MODE=false` → needs a valid `GEMINI_API_KEY`

---

## 7. Blockchain keys (optional for testing)

If `POLYGON_PRIVATE_KEY` or `AGREEMENT_CONTRACT_ADDRESS` is missing/wrong, the blockchain badge won't appear **but the bot will still work** — it falls back gracefully.

To get test MATIC for Polygon Amoy: https://faucet.polygon.technology

---

## Full Setup (copy-paste for your friend)

```bash
# 1. Clone the repo
git clone <repo-url>
cd negot8

# 2. Create Python virtual environment
python3 -m venv venv
source venv/bin/activate      # macOS/Linux

# 3. Install dependencies
pip install -r requirements.txt

# 4. Set up environment variables
cp .env.example .env
# Edit .env — fill in TELEGRAM_BOT_TOKEN_A, TELEGRAM_BOT_TOKEN_B at minimum
# Set MOCK_MODE=true to skip needing a Gemini API key

# 5. Start the backend bots
cd backend
python3 -u run.py

# 6. (Optional) Start the Next.js dashboard
cd ../dashboard
npm install
npm run dev
```

---

## Minimum viable `.env` to get bots running

```env
TELEGRAM_BOT_TOKEN_A=<your bot A token from BotFather>
TELEGRAM_BOT_TOKEN_B=<your bot B token from BotFather>
MOCK_MODE=true
DATABASE_PATH=negot8.db
```

Everything else is optional for basic testing.