matrix-quotes-bot/README.md

# 🎃 Ancestor Quote Bot

A Matrix chatbot that responds to `!quote` commands with random quotes from Darkest Dungeons.

## Quick Start

```bash
# 1. Update .env file (create from template)
cp .env.example .env
nano .env  # Edit MATRIX_ACCESS_TOKEN and MATRIX_HOME_SERVER

# 2. Build Docker image
docker build -t ancestor-quote-bot .

# 3. Run the bot
docker run --rm \
  -e MATRIX_HOME_SERVER=https://matrix.org \
  -e MATRIX_ACCESS_TOKEN=your_access_token_here \
  ancestor-quote-bot
```

## Deployment Options

### Option A: Pass env vars via `docker run` (Recommended)
```bash
docker run --rm \
  -e MATRIX_HOME_SERVER=https://matrix.org \
  -e MATRIX_ACCESS_TOKEN=your_access_token_here \
  -e BOT_COMMAND=!quote \
  ancestor-quote-bot
```

### Option B: Mount .env file directly
```bash
docker run --rm \
  -v $(pwd)/.env:/app/.env \
  ancestor-quote-bot
```

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `MATRIX_HOME_SERVER` | Matrix homeserver URL (e.g., https://matrix.org) | https://matrix.org |
| `MATRIX_ACCESS_TOKEN` | Bot access token for authentication | REQUIRED |
| `BOT_COMMAND` | Command trigger to request a quote | !quote |

## Getting an Access Token

1. Go to [Matrix Registration API](https://matrix.org/docs/projects/registration/matrix-registration-api)
2. Or use your Matrix admin panel to create a bot account
3. Get the access token from your Matrix settings

## How It Works

1. The bot connects to your Matrix homeserver using the provided access token
2. Once joined to a room, it listens for messages containing the trigger command
3. When triggered, it selects a random quote from `quotes.json` and replies instantly

## Usage

```bash
# Invite the bot to a room:
# @ancestor-quote-bot:matrix.org (or your custom username)

# In any Matrix room, type:
!quote

# Bot responds with:
"Dispatch this thug in brutal fashion, that all may hear of your arrival!"
```

## License

ISC