readme

README.md

@@ -1,2 +1,64 @@
-# grepo-remote
+# Grepolis Remote Control (GRC)
 
+A sophisticated remote management dashboard and automation relay for Grepolis. GRC allows you to monitor your towns and issue building/recruitment commands from a centralized web interface, bypassing the need to have the game tab active at all times.
+
+## 🚀 Key Features
+
+- **Real-time Town Monitoring**: Track resources (Wood, Stone, Iron, Silver), Population, God, Points, and World placement across all your towns.
+- **Remote Commands**: Issue "Build" and "Recruit" orders directly from the dashboard.
+- **Infinite External Queue**: Commands are stored in a local database and executed by the script as soon as in-game slots or resources become available.
+- **Smart UI Indicators**: 
+    - **Resource Validation**: Live checks against town resources; warns you if you can't afford a command.
+    - **Dependency Tracking**: Automatically detects missing building prerequisites or required research.
+    - **Building Costs & Times**: Displays exact requirements and duration for the next upgrade level.
+- **Modular Architecture**: Cleanly separated frontend (JS/CSS) and backend (Python/Flask) for easy maintenance.
+- **Greek Localization**: Fully localized unit and building names.
+
+## 🏗 System Architecture
+
+The project consists of three main parts:
+
+1.  **Tampermonkey Script (`GrepolisRemoteControl.user.js`)**: 
+    - The "Worker" that runs inside your Grepolis browser tab.
+    - Scrapes game state (ITowns, GameData) and pushes it to the relay server.
+    - Polls the relay for pending commands and executes them using in-game AJAX calls.
+2.  **Relay Server (Python/Flask)**:
+    - **`app.py`**: Entry point and CORS configuration.
+    - **`db.py`**: SQLite database management for storing town states and command history.
+    - **`routes/`**: API endpoints for state synchronization and dashboard data.
+3.  **Dashboard (HTML/JS/CSS)**:
+    - **`templates/dashboard.html`**: The main interface structure.
+    - **`/static/js/`**: Modular logic split into State, API, and UI Components (TownViewer, CommandForm, CommandLog).
+
+## 🛠 Setup & Installation
+
+### 1. Backend Setup
+Ensure you have Python 3.x installed.
+```bash
+pip install -r requirements.txt
+python app.py
+```
+By default, the server runs on `http://localhost:5050` (or your configured domain).
+
+### 2. Userscript Setup
+1. Open Tampermonkey in your browser.
+2. Create a new script and paste the contents of `GrepolisRemoteControl.user.js`.
+3. Update the `BASE_URL` constant (line 17) to point to your relay server.
+4. Save and refresh your Grepolis tab.
+
+## 🕹 How to Use
+
+1. **Check Connectivity**: Open the Dashboard. Look for the "● Server" and "● Script" indicators in the top right. Both should be green.
+2. **Select a Town**: Click a town from the left sidebar to view detailed resources, buildings, and current build queue.
+3. **Issue a Command**:
+    - Select **Build** or **Recruit** from the dropdown.
+    - Choose the target (Building or Unit).
+    - If resources are lacking, the system will ask for confirmation to add it to the wait-list.
+    - If dependencies are missing, a red warning will prevent submission.
+4. **Monitor the Log**: View the status of your commands (Pending, Executing, Done, or Failed) in the bottom log panel.
+
+## ⚠️ Disclaimer
+This is an automation tool. Using scripts like this may violate the game's Terms of Service. Use responsibly and at your own risk.
+
+---
+*Created with ❤️ for Grepolis players.*