# Repository Guidelines

## Project Structure & Module Organization

This repository is a small, script-first Python project. `bot.py` is the long-running Twitch IRC bot that controls MPD. `_twitch.py` holds shared Helix auth and token-refresh helpers for the CLI tools. `search-game.py` resolves free-form game queries to Twitch category IDs, and `set-channel.py` updates the channel title and game. `examples/stream.sh` is the interactive pre-stream wrapper that writes `examples/stream.json`. Keep secret-bearing runtime files in `.env` or `.env.broadcaster`; only the `*.example` templates are tracked.

## Build, Test, and Development Commands

There is no package build step. Use direct script execution:

```bash
pip install python-mpd2
python3 bot.py
TWITCH_BOT_DEBUG=1 python3 bot.py
./search-game.py "DOOM"
./set-channel.py --dry-run --game-id 517520 "Stream title"
./examples/stream.sh
```

`python3 bot.py` runs the chat bot. `TWITCH_BOT_DEBUG=1` dumps raw IRC lines for troubleshooting. The two CLI helpers are intended to be run directly, and `stream.sh` composes them into a guided flow.

## Coding Style & Naming Conventions

Match the existing style: Python 3.10+, standard library first, minimal dependencies, and small top-level scripts instead of packages. Use 4-space indentation in Python and keep helpers simple and explicit. Follow the current naming pattern: `snake_case` for functions and variables, short module names for single-purpose scripts, and uppercase constants such as `SKIP_COOLDOWN`. Shell scripts should keep `set -euo pipefail`.

## Testing Guidelines

There is no automated test suite yet. Before opening a PR, do targeted smoke tests for the code path you changed. Examples: run `python3 bot.py` against a local MPD instance, run `./search-game.py "Heroes"`, or use `./set-channel.py --dry-run ...` to validate argument handling without issuing a PATCH. If you add tests later, place them under a new `tests/` directory and use `test_*.py`.

## Commit & Pull Request Guidelines

Git history is minimal; the current commit style is short and imperative (`Initial version`). Keep commits concise, scoped, and written in the imperative mood. PRs should explain the user-visible behavior change, note any `.env` or token-scope impact, and include terminal output or screenshots when changing interactive flows such as `examples/stream.sh`.

## Security & Configuration Tips

Do not merge `.env` and `.env.broadcaster`. The bot account and broadcaster account require different scopes and are intentionally separated. Never commit live tokens or generated `examples/stream.json`.