docs: update README.md

Author: S1M0N38

README.md

@@ -16,181 +16,93 @@
 
 ---
 
-## Overview
-
 BalatroLLM is a bot that uses Large Language Models (LLMs) to play [Balatro](https://www.playbalatro.com/), the popular roguelike poker deck-building game. The bot analyzes game states, makes strategic decisions, and executes actions through the [BalatroBot](https://github.com/coder/balatrobot) client.
 
 The system combines multiple components to make informed decisions:
 
-- **Strategy templates** (`STRATEGY.md.jinja`) - Define playing style and approach
+- **Strategy templates** (`STRATEGY.md.jinja`) - Define the playing style and approach
 - **Game state analysis** (`GAMESTATE.md.jinja`) - Current game situation and available options
 - **Memory system** (`MEMORY.md.jinja`) - Historical context from previous decisions
 - **Action tools** (`TOOLS.json`) - Available game actions and their parameters
 
-These components are processed together in a single LLM call, enabling the bot to understand the current situation and choose the optimal action based on its configured strategy.
-
-## Quick Start
+These components are processed together in a single LLM call, enabling the bot to understand the current situation and perform the optimal tool call based on its configured strategy.
 
-### Prerequisites
+## 📋 Requirements
 
 - [uv](https://docs.astral.sh/uv/) package manager
 - Balatro instance with [BalatroBot](https://github.com/coder/balatrobot) mod installed
 
-### Setup
+> [!IMPORTANT]
+> Setting up Balatro with the BalatroBot mod requires careful configuration. Please refer to the [BalatroBot](https://github.com/coder/balatrobot) documentation and follow the instructions step by step.
+
+## 📦 Installation
+
+1. Clone the repository
 
 ```bash
-# 1. Clone the repository
 git clone https://github.com/coder/balatrollm.git
 cd balatrollm
+```
 
-# 2. Create and activate environment
-uv sync
-
-# 3. Configure environment
-cp .envrc.example .envrc
-# edit .envrc with your OpenRouter API key
+2. Create environment and install dependencies
 
-# 4. Activate environment
-source .envrc
+```bash
+uv sync --no-dev
 ```
 
-#### Environment Variables
-
-**OpenRouter API Key** (provides access to all LLM providers)
+3. Activate environment
 
 ```bash
-export OPENROUTER_API_KEY="your-openrouter-api-key"
+source .venv/bin/activate
 ```
 
-Get your API key from: https://openrouter.ai/keys
+> [!TIP]
+> You can use [direnv](https://direnv.net/) to automatically activate the environment when you enter the project directory. The `.envrc.example` file contains an example configuration for direnv.
 
-The CLI uses sensible defaults for all other configuration:
 
-- Default model: `openai/gpt-oss-20b`
-- Default base URL: `https://openrouter.ai/api/v1`
-- Default API key: `OPENROUTER_API_KEY` environment variable
-- Default strategy: `default`
+## ⚙️ LLM Configuration
 
-### Usage
+BalatroLLM performs single requests to an OpenAI-compatible chat/completions endpoint. You need to configure:
 
-#### Quick Start
+- `--model`: LLM model identifier
+- `--base-url`: OpenAI-compatible API base URL
+- `--api-key`: API key (if required)
 
-```bash
-# 1. Start Balatro with BalatroBot mod (in separate terminal)
-./balatro.sh
+The default configuration uses [OpenRouter](https://openrouter.ai/), which provides access to many LLMs:
 
-# 2. Run the bot with default settings
-balatrollm
-
-# 3. Run with optimizations for different environments
-balatrollm --no-screenshot                    # Headless mode (no screenshots)
-balatrollm --use-default-paths              # Distributed systems
-balatrollm --no-screenshot --use-default-paths  # Both optimizations
-```
+- `--model openai/gpt-oss-20b`: Small, fast, and affordable model
+- `--base-url https://openrouter.ai/api/v1`: OpenRouter API base URL
+- `--api-key $OPENROUTER_API_KEY`: It's recommended to export the API key in the `.envrc` file.
 
-#### `balatrollm` - Command Line Interface
+> [!TIP]
+> After configuring the base URL and API key, you can check the available models by running `balatrollm --list-models`
 
-```bash
-balatrollm --help
-```
+## ⚡ Usage
 
-```
-usage: balatrollm [-h] [-m MODEL] [-l] [-s STRATEGY] [-u BASE_URL] [-k API_KEY] [-c CONFIG]
-                  [-d RUNS_DIR] [-r RUNS] [-p PORT] [--no-screenshot] [--use-default-paths]
-                  {benchmark} ...
-
-LLM-powered Balatro bot
-
-positional arguments:
-  {benchmark}           Available commands
-    benchmark           Analyze runs and generate leaderboards
-
-options:
-  -h, --help            show this help message and exit
-  -m, --model MODEL     Model name to use from OpenAI-compatible API (default: openai/gpt-oss-20b)
-  -l, --list-models     List available models from OpenAI-compatible API and exit
-  -s, --strategy STRATEGY
-                        Name of the strategy to use (default: default)
-  -u, --base-url BASE_URL
-                        OpenAI-compatible API base URL (default: https://openrouter.ai/api/v1)
-  -k, --api-key API_KEY
-                        API key (default: OPENROUTER_API_KEY env var)
-  -d, --runs-dir RUNS_DIR
-                        Base directory for storing run data (default: current directory)
-  -r, --runs RUNS       Number of times to run the bot with the same configuration (default: 1)
-  -p, --port PORT       Port for BalatroBot client connection (can specify multiple, default: 12346)
-  --no-screenshot       Disable taking screenshots during gameplay (use for headless mode)
-  --use-default-paths   Use BalatroBot's default storage paths (use for distributed systems)
-```
+The typical workflow to run BalatroLLM is:
 
-#### `Makefile` - Development Workflow
+1. Start Balatro with the BalatroBot mod:
 
 ```bash
-make help
+bash balatro.sh
 ```
 
-```
-BalatroLLM Development Makefile
-
-Available targets:
-  help               Show this help message
-  install            Install package dependencies
-  install-dev        Install package with development dependencies
-  lint               Run ruff linter (check only)
-  lint-fix           Run ruff linter with auto-fixes
-  format             Run ruff formatter
-  typecheck          Run type checker
-  quality            Run all code quality checks
-  test               Run tests
-  test-cov           Run tests with coverage report
-  all                Run all code quality checks and tests
-  clean              Clean build artifacts and caches
-  setup              Kill previous instances and start Balatro
-  teardown           Stop Balatro processes
-  balatrobench       Run benchmark for all models and generate analysis
-```
-
-#### `balatro.sh` - Game Automation
+2. Run the bot, typically with multiple runs using the same configuration:
 
 ```bash
-./balatro.sh --help
+balatrollm --runs-per-seed 3 --seed ABCDEFG
 ```
 
-```
-Usage: ./balatro.sh [OPTIONS]
-       ./balatro.sh -p PORT [OPTIONS]
-       ./balatro.sh --kill
-       ./balatro.sh --status
-
-Options:
-  -p, --port PORT  Specify port for Balatro instance (can be used multiple times)
-                   Default: 12346 if no port specified
-  --headless       Enable headless mode (sets BALATROBOT_HEADLESS=1)
-  --fast           Enable fast mode (sets BALATROBOT_FAST=1)
-  --audio          Enable audio (disabled by default, sets BALATROBOT_AUDIO=1)
-  --kill           Kill all running Balatro instances and exit
-  --status         Show information about running Balatro instances
-  -h, --help       Show this help message
-
-Examples:
-  ./balatro.sh                            # Start single instance on default port 12346
-  ./balatro.sh -p 12347                   # Start single instance on port 12347
-  ./balatro.sh -p 12346 -p 12347          # Start two instances on ports 12346 and 12347
-  ./balatro.sh --headless --fast          # Start with headless and fast mode on default port
-  ./balatro.sh --audio                    # Start with audio enabled on default port
-  ./balatro.sh --kill                     # Kill all running Balatro instances
-  ./balatro.sh --status                   # Show running instances
-```
+3. Generate benchmark reports from the runs:
 
-## Contributing
+```bash
+balatrobench --models
+```
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
+> [!TIP]
+> You can run `bash balatro.sh --help`, `balatrollm --help`, and `balatrobench --help` to see all available options.
 
-- Setting up the development environment
-- Code style and conventions
-- Testing guidelines
-- Release process
 
-## License
+## 📚 Documentation
 
-This project is licensed under the MIT License – see the [LICENSE](LICENSE) file for details.
+https://coder.github.io/balatrollm/