docs: improve docs and fix inconsistencies

Closes #62

Author: S1M0N38

docs/cli.md

@@ -28,29 +28,66 @@ This means CLI flags override config file values, which override environment var
 
     ```bash
     export BALATROLLM_CONFIG="config/example.yaml"
-    balatrollm --model openai/gpt-5
+    balatrollm
     ```
 
     This is the **only** `BALATROLLM_*` environment variable that does not have a corresponding CLI flag — the user can simply provide the config file path as a positional argument instead.
 
     **Precedence:** If both the `CONFIG` argument and `BALATROLLM_CONFIG` are provided, the CLI argument takes precedence and `BALATROLLM_CONFIG` is ignored.
 
+## Configuration file (YAML)
+
+The YAML configuration file uses the same field names as the CLI flags (minus the `--`), for example:
+
+- CLI `--model` → YAML `model`
+- CLI `--base-url` → YAML `base_url`
+
+For a full annotated example, see [`config/example.yaml`](https://github.com/coder/balatrollm/blob/main/config/example.yaml).
+
+### `model` (required)
+
+`model` is required, but it can come from **any** config source (YAML config, env var, or CLI flag). If you set `model:` in your YAML file, you do not need to also pass `--model`.
+
+```yaml
+model:
+  - openai/gpt-4o
+```
+
+### `model_config` (advanced)
+
+The YAML file also supports an optional `model_config` mapping for advanced provider/model request knobs. BalatroLLM deep-merges your `model_config` into built-in defaults (including nested fields like `extra_headers` and `extra_body`) and then passes the result directly to the OpenAI-compatible chat completions request.
+
+Common examples include `temperature`, `max_tokens`, `seed`, `parallel_tool_calls`, `tool_choice`, plus provider-specific settings via `extra_body` (e.g., OpenRouter).
+
+```yaml
+model_config:
+  temperature: 0.2
+  max_tokens: 2048
+  extra_body:
+    reasoning:
+      effort: medium
+```
+
 ## Options
 
-| CLI Flag              | Environment Variable  | Default                        | Description                  |
-| --------------------- | --------------------- | ------------------------------ | ---------------------------- |
-| `--model MODEL`       | `BALATROLLM_MODEL`    | *(required)*                   | LLM model(s) to use          |
-| `--seed SEED`         | `BALATROLLM_SEED`     | `AAAAAAA`                      | Game seed(s)                 |
-| `--deck DECK`         | `BALATROLLM_DECK`     | `RED`                          | Deck code(s)                 |
-| `--stake STAKE`       | `BALATROLLM_STAKE`    | `WHITE`                        | Stake code(s)                |
-| `--strategy STRATEGY` | `BALATROLLM_STRATEGY` | `default`                      | Strategy name(s)             |
-| `--parallel N`        | `BALATROLLM_PARALLEL` | `1`                            | Concurrent game instances    |
-| `--host HOST`         | `BALATROLLM_HOST`     | `127.0.0.1`                    | BalatroBot host              |
-| `--port PORT`         | `BALATROLLM_PORT`     | `12346`                        | Starting port                |
-| `--base-url URL`      | `BALATROLLM_BASE_URL` | `https://openrouter.ai/api/v1` | LLM API base URL             |
-| `--api-key KEY`       | `BALATROLLM_API_KEY`  | *None*                         | LLM API key                  |
-| `--views`             | `BALATROLLM_VIEWS`    | `False`                        | Enable views HTTP server     |
-| `--dry-run`           | -                     | `False`                        | Show tasks without executing |
+| CLI Flag              | Environment Variable  | Default                        | Description                                         |
+| --------------------- | --------------------- | ------------------------------ | --------------------------------------------------- |
+| `--model MODEL`       | `BALATROLLM_MODEL`    | *(required)*                   | LLM model(s) to use (or set `model:` in YAML)       |
+| `--seed SEED`         | `BALATROLLM_SEED`     | `AAAAAAA`                      | Game seed(s)                                        |
+| `--deck DECK`         | `BALATROLLM_DECK`     | `RED`                          | Deck code(s)                                        |
+| `--stake STAKE`       | `BALATROLLM_STAKE`    | `WHITE`                        | Stake code(s)                                       |
+| `--strategy STRATEGY` | `BALATROLLM_STRATEGY` | `default`                      | Strategy name(s)                                    |
+| `--parallel N`        | `BALATROLLM_PARALLEL` | `1`                            | Concurrent game instances                           |
+| `--host HOST`         | `BALATROLLM_HOST`     | `127.0.0.1`                    | BalatroBot host                                     |
+| `--port PORT`         | `BALATROLLM_PORT`     | `12346`                        | Starting port                                       |
+| `--base-url URL`      | `BALATROLLM_BASE_URL` | `https://openrouter.ai/api/v1` | LLM API base URL                                    |
+| `--api-key KEY`       | `BALATROLLM_API_KEY`  | *None*                         | LLM API key                                         |
+| `--views`             | `BALATROLLM_VIEWS`    | `False`                        | Enable views HTTP server (set `BALATROLLM_VIEWS=1`) |
+| `--dry-run`           | -                     | `False`                        | Show tasks without executing                        |
+
+!!! note "How Balatro instances are started"
+
+    `balatrollm` starts/stops Balatro instances automatically via `balatrobot`. With `--parallel N`, it spawns instances on ports `--port` through `--port + N - 1` (`port..port+parallel-1`).
 
 !!! note "Multiple Values"
 
@@ -74,7 +111,7 @@ balatrollm config/example.yaml
 
 # Run with configuration file via environment variable
 export BALATROLLM_CONFIG="config/example.yaml"
-balatrollm --model openai/gpt-5
+balatrollm
 
 # Run with config file and override specific options
 balatrollm config/example.yaml --model openai/gpt-5 --seed BBBBBBB
@@ -97,6 +134,9 @@ balatrollm --model openai/gpt-4o --strategy my_custom_strategy
 
 # Enable views overlay on port 12345
 balatrollm --model openai/gpt-4o --views
+
+# Enable views overlay via environment variable (0/1)
+BALATROLLM_VIEWS=1 balatrollm --model openai/gpt-4o
 # Access views at:
 #   http://localhost:12345/views/task.html
 #   http://localhost:12345/views/responses.html
@@ -108,6 +148,32 @@ balatrollm --model openai/gpt-4o --views
 
 For more information about strategies, see the [Strategies documentation](strategies.md).
 
+## Run artifacts / outputs
+
+`balatrollm` writes run artifacts to `./runs/` (relative to your current working directory).
+
+```text
+runs/
+  latest.json
+  vX.Y.Z/<strategy>/<vendor>/<model>/<timestamp>_<deck>_<stake>_<seed>/
+    task.json
+    strategy.json
+    run.log
+    requests.jsonl
+    responses.jsonl
+    gamestates.jsonl
+    stats.json
+    screenshots/
+```
+
+- `task.json` / `strategy.json`: resolved task metadata and the strategy manifest used for the run.
+- `requests.jsonl` / `responses.jsonl`: LLM requests and responses (JSONL, one object per line).
+- `gamestates.jsonl`: game state snapshots after each action.
+- `stats.json`: aggregated statistics for the run.
+- `screenshots/`: screenshots captured during the run.
+- `run.log`: logs captured during the run.
+- `runs/latest.json`: updated each run; used by the `--views` overlays to locate the latest `task.json` and `responses.jsonl`.
+
 ## BalatroBot Configuration
 
 BalatroBot instances spawned by BalatroLLM can be configured through `BALATROBOT_*` environment variables. These settings control how Balatro runs during automated gameplay.

docs/contributing.md

@@ -19,28 +19,15 @@ We use [direnv](https://direnv.net/) to automatically manage environment variabl
 
     The `.envrc` file may contain API keys. **Never commit this file**.
 
-**Example `.envrc` configuration:**
+Start from the versioned template:
 
 ```bash
-# Load the virtual environment
-source .venv/bin/activate
-
-# Python-specific variables
-export PYTHONUNBUFFERED="1"
-export PYTHONPATH="${PWD}/src:${PYTHONPATH}"
-export PYTHONPATH="${PWD}/tests:${PYTHONPATH}"
-
-# BALATROBOT env vars
-export BALATROBOT_FAST=1
-export BALATROBOT_DEBUG=1
-export BALATROBOT_RENDER_ON_API=0
-export BALATROBOT_HEADLESS=0
-
-# BALATROLLM env vars
-export BALATROLLM_API_KEY="sk-..."
-export BALATROLLM_BASE_URL="https://openrouter.ai/api/v1"
+cp .envrc.example .envrc
+direnv allow
 ```
 
+Then edit `.envrc` and set at minimum `BALATROLLM_API_KEY` (and `BALATROLLM_MODEL` if you aren't providing a YAML config or `--model`).
+
 ## Development Setup
 
 ### 1. Clone the Repository

docs/strategies.md

@@ -188,7 +188,7 @@ Defines the function calls available to the LLM during different game phases. Th
 
 ### Available Game States
 
-Tools are organized by game state. The `TOOLS.json` file maps each state to its available tools:
+Tools are organized by game state. The `TOOLS.json` file maps each state to its available tools.
 
 | Game State             | Description           | Available Tools                                           |
 | ---------------------- | --------------------- | --------------------------------------------------------- |
@@ -197,6 +197,15 @@ Tools are organized by game state. The `TOOLS.json` file maps each state to its
 | `BLIND_SELECT`         | Blind selection phase | `select`, `skip`                                          |
 | `SMODS_BOOSTER_OPENED` | Pack opening phase    | `pack` (select cards or skip)                             |
 
+!!! note "BLIND_SELECT and ROUND_EVAL Behavior"
+
+    The current `balatrollm` bot loop does not delegate `BLIND_SELECT` or `ROUND_EVAL` to the LLM (see `src/balatrollm/bot.py`).
+
+    - `ROUND_EVAL` always calls `cash_out`
+    - `BLIND_SELECT` always calls `select` (never `skip`) because Tags are not supported yet by `balatrobot`; skipping blinds would collect Tags the bot can't use
+
+    This "always play the blind" policy is a reasonable baseline for `RED` deck on `WHITE` stake.
+
 ### Common Tools
 
 **SELECTING_HAND phase:**
@@ -219,7 +228,7 @@ Tools are organized by game state. The `TOOLS.json` file maps each state to its
 **BLIND_SELECT phase:**
 
 - `select`: Select a blind to play
-- `skip`: Skip the current blind (if allowed)
+- `skip`: Skip the current blind (if allowed). *(Currently not used by `balatrollm`; Tag handling isn’t supported yet.)*
 
 ## Strategy Validation
 
@@ -281,7 +290,7 @@ Common issues:
 1. Fork the BalatroLLM repository
 2. Create a feature branch: `git checkout -b feat/add-strategy-your_strategy_name`
 3. Add your strategy directory with all required files
-4. Commit following conventional commits: `feat: add [strategy_name] strategy`
+4. Commit following conventional commits: `feat(strategy): add [strategy_name] strategy`
 5. Open a pull request with:
     - Clear title describing your strategy
     - Brief description of the strategy's approach