init: mostly vibed

1 files changed, 134 insertions, 0 deletions

diff --git a/docs/osterman.md b/docs/osterman.md
new file mode 100644
index 0000000..2e81629
--- /dev/null
+++ b/docs/osterman.md
@@ -0,0 +1,134 @@
+# 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 |