init

negot8/SETUP.md

@@ -0,0 +1,138 @@
+# 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.