# osterman

Channel moderation bot. Manages bans, kicks, mutes, auto-modes, content filters,
and idle tracking.

## Dependencies

No external libraries required.

## Plugins

| File | Role |
|------|------|
| `protect.py` | Setup, passive protection: flood, caps, repeat, badword, clone, join flood |
| `commands.py` | All user-facing moderation and config commands |
| `tracking.py` | SQLite event log, greeting, `!seen`, `!info`, `!log` |
| `idle.py` | Idle detection tick, `!afk`, `!idle` |
| `help.py` | Three-level help system |

## Message routing

| Output type | Delivery |
|-------------|----------|
| `!seen`, `!idle <nick>` results | Channel message |
| `!info`, `!log` results | PM to nick |
| `!ban list`, `!config`, `!filter list`, `!badword list` | PM to nick |
| All other command feedback (errors, confirmations) | IRC NOTICE to nick |
| Greetings, idle warns, bad word warn | IRC NOTICE to nick |

## Help system

```
!help                       list topics
!help <topic>               list commands for a topic
!help <topic> <cmd>         description and usage for a command
!help <cmd>                 description and usage (topic not required)
```

Topics: `mod`, `config`, `track`, `idle`, `admin`

## Commands

### Moderation (owner / ACL / op)

| Command | Short | Description |
|---------|-------|-------------|
| `!kick <nick> [reason]` | `!k` | Kick |
| `!ban <nick\|mask> [reason]` | `!b` | Ban + kick |
| `!ban list` | `!b list` | View channel ban list (PM) |
| `!bankick <nick\|mask> [reason]` | `!bk` | Ban + kick (explicit) |
| `!unban <nick\|mask>` | `!ub` | Remove ban |
| `!tempban <nick\|mask> <min> [reason]` | `!tb` | Timed ban (auto-lifts) |
| `!mute <nick\|mask>` | `!mu` | Quiet (+q) |
| `!unmute <nick\|mask>` | `!umu` | Unquiet (-q) |
| `!voice <nick>` | `!v` | Give voice (+v) |
| `!devoice <nick>` | `!dv` | Remove voice |
| `!op <nick>` | `!o` | Give op (+o) |
| `!deop <nick>` | `!do` | Remove op |
| `!halfop <nick>` | `!hop` | Give halfop (+h) |
| `!dehalfop <nick>` | `!dhop` | Remove halfop |
| `!lock [m\|i]` | `!lk` | Lock channel (+mi, +m, or +i) |
| `!unlock [m\|i]` | `!ulk` | Unlock channel |

### Auto-modes (owner / ACL / op, per channel)

| Command | Short | Description |
|---------|-------|-------------|
| `!autoop <add\|del\|list> [nick\|mask]` | `!ao` | Auto +o on join |
| `!autovoice <add\|del\|list> [nick\|mask]` | `!av` | Auto +v on join |
| `!autohalfop <add\|del\|list> [nick\|mask]` | `!ahop` | Auto +h on join |

### Config / lists (owner / ACL)

| Command | Short | Description |
|---------|-------|-------------|
| `!blacklist <add\|del\|list> [mask]` | `!bl` | Global ban list (all channels) |
| `!whitelist <add\|del\|list> [mask]` | `!wl` | Global bypass list |
| `!except <add\|del\|list> [mask]` | `!ex` | Per-channel bypass list |
| `!acl <add\|del\|list> [nick]` | (none) | Trusted nicks (can use mod commands) |
| `!filter <add\|del\|list> [pattern]` | `!f` | Per-channel regex content filter |
| `!badword <add\|del\|list> [word]` | `!bw` | Per-channel word block list |
| `!set <key> <value>` | `!s` | Set a config value (in channel: per-channel; in PM: global) |
| `!config [#channel]` | `!cfg` | Show channel config (PM) |
| `!idle <on\|off>` | `!id` | Toggle idle detection |

### Tracking

| Command | Auth | Description |
|---------|------|-------------|
| `!seen <nick>` | anyone | Last time nick was seen in this channel. Responds in channel. Owner/ACL may call from PM for cross-channel lookup. |
| `!info <nick>` | anyone | Nick summary scoped to this channel (PM). Owner/ACL may call from PM for global lookup. |
| `!idle <nick>` | anyone | How long nick has been idle in this channel. Responds in channel. |
| `!log <nick> [n]` | owner / ACL | Full event log for nick (PM) |
| `!afk` | anyone | Reset your idle timer |

### Admin (owner)

| Command | Short | Description |
|---------|-------|-------------|
| `!join <#channel>` | `!j` | Join a channel |
| `!part [#channel]` | `!p` | Leave a channel |
| `!chans` | `!c` | List channels |

## Configurable settings (`!set <key> <value>`)

| Key | Default | Description |
|-----|---------|-------------|
| `flood_threshold` | 5 | Messages before flood action |
| `flood_window_sec` | 10 | Flood detection window (seconds) |
| `caps_filter` | 1 | Enable caps filter (0/1) |
| `caps_percent` | 70 | Caps percentage threshold |
| `caps_min_len` | 10 | Minimum message length to check |
| `repeat_filter` | 1 | Enable repeat filter (0/1) |
| `repeat_threshold` | 3 | Repeated messages before action |
| `repeat_window_sec` | 30 | Repeat detection window (seconds) |
| `clone_limit` | 2 | Max connections from same host |
| `join_flood_filter` | 1 | Enable join flood filter (0/1) |
| `join_flood_count` | 5 | Joins before action |
| `join_flood_window` | 10 | Join flood window (seconds) |
| `nick_flood_filter` | 1 | Enable nick flood filter (0/1) |
| `nick_flood_count` | 3 | Nick changes before action |
| `nick_flood_window` | 60 | Nick flood window (seconds) |
| `badword_action` | kick | Action on badword: `kick` or `warn` |
| `tempban_max_min` | 60 | Max duration for `!tempban` (minutes) |
| `idle_warn_min` | 45 | Minutes idle before warning |
| `idle_kick_min` | 60 | Minutes idle before kick |
| `log_limit` | 6 | Default number of events shown by `!log` |
| `greet` | 1 | Send join greeting (0/1) |

## Config keys

| Key | Description |
|-----|-------------|
| `[osterman] db_path` | Path to JSON database file |