init: mostly vibed

1 files changed, 122 insertions, 0 deletions

diff --git a/docs/jeeves.md b/docs/jeeves.md
new file mode 100644
index 0000000..77bd5e7
--- /dev/null
+++ b/docs/jeeves.md
@@ -0,0 +1,122 @@
+# jeeves
+
+Combined-features IRC bot. Brings together DJ queue management, duck hunting,
+recipes, news and weather, quote bank, image rendering, and keyword responses
+in a single bot with a shared runtime-configurable settings store.
+
+## Dependencies
+
+- Sopel IRC framework
+- Pillow (`pip install Pillow`) - only needed for `!draw`; all other features
+  work without it
+
+## Commands
+
+### DJ (anyone / op for controls)
+| Command | Description |
+|---------|-------------|
+| `!dj <url>` | Queue a YouTube URL (shorts, embeds, live not accepted) |
+| `!np` | Show currently playing track |
+| `!queue` | List up to 4 upcoming tracks |
+| `!loop` | Show loop state |
+| `!play` | Start or resume playback (op) |
+| `!stop` | Pause playback (op) |
+| `!skip` | Skip to next track (op) |
+| `!remove` | Remove current track from queue (op) |
+| `!loop <on\|off>` | Toggle queue looping (op) |
+| `!clear` | Clear queue and stop playback (op) |
+
+### Duck hunting (anyone in channel / op for control)
+| Command | Description |
+|---------|-------------|
+| `!bang` | Fire at the current duck |
+| `!reload` | Refill ammo (3-second cooldown) |
+| `!score` | Top 5 players for this channel |
+| `!score clear` | Clear scores for this channel (op/owner) |
+| `!hunt` | Show hunt state (includes current spawn/flee times) |
+| `!hunt start` | Start the hunt (op/owner) |
+| `!hunt stop` | Stop the hunt (op/owner) |
+
+### Recipes (anyone in channel)
+| Command | Description |
+|---------|-------------|
+| `!breakfast [list]` | Random breakfast suggestion, or list all |
+| `!lunch [list]` | Random lunch suggestion, or list all |
+| `!dinner [list]` | Random dinner suggestion, or list all |
+| `!snack [list]` | Random snack suggestion, or list all |
+| `!recipe <name>` | Full recipe: name, ingredients, steps |
+
+### News and weather (anyone)
+| Command | Description |
+|---------|-------------|
+| `!weather <city>` | Current weather conditions |
+| `!forecast <city>` | 3-day weather forecast |
+| `!headlines [global\|mena\|egypt] [count]` | Latest RSS headlines |
+| `!news` | Show auto-broadcast state |
+| `!news on\|off` | Enable/disable auto-broadcast (op/owner) |
+
+### Quotes (anyone / op for management)
+| Command | Description |
+|---------|-------------|
+| `!quote` | Post a random quote |
+| `!quote add <text>` | Add a quote (op/owner) |
+| `!quote del <N>` | Delete quote by index (op/owner) |
+| `!quote list` | Show total quote count |
+| `!quotes` | Show auto-post state |
+| `!quotes on\|off` | Enable/disable auto-posting (op/owner) |
+
+### Art (anyone in channel)
+| Command | Description |
+|---------|-------------|
+| `!draw [<lines>] <url>` | Render image as mIRC colour art (lines 4-12) |
+
+### Config (owner / op)
+| Command | Description |
+|---------|-------------|
+| `!set <key> <value>` | Set a config value (in channel: per-channel; in PM: global, owner only) |
+| `!config [#channel]` | Show all config values for a channel |
+
+### Admin (owner)
+| Command | Description |
+|---------|-------------|
+| `!join #channel` | Join a channel |
+| `!part [#channel]` | Leave a channel |
+| `!chans` | List joined channels |
+| `!pause` | Pause keyword responses |
+| `!resume` | Resume keyword responses |
+
+### Help
+| Command | Description |
+|---------|-------------|
+| `!help` | Topics overview |
+| `!help <topic>` | Commands in that topic |
+| `!help <cmd>` | Command description |
+
+## Runtime config keys
+
+All keys are set via `!set <key> <value>`. Per-channel keys can be set in a
+channel (affecting that channel only) or in PM (setting the global default).
+Global-only keys must be set in PM by the owner.
+
+| Key | Default | Scope | Description |
+|-----|---------|-------|-------------|
+| `dj_track_duration` | 120 | global | Seconds per track before auto-advance |
+| `dj_queue_cap` | 50 | global | Max tracks in queue |
+| `art_height` | 6 | global | Default lines for `!draw` (4-12) |
+| `duck_spawn_min` | 60 | per-channel | Min seconds between duck spawns |
+| `duck_spawn_max` | 300 | per-channel | Max seconds between duck spawns |
+| `duck_flee_time` | 45 | per-channel | Seconds before duck flees |
+| `duck_idle_rounds` | 3 | per-channel | Empty rounds before auto-stop (0=off) |
+| `news_interval` | 90 | per-channel | Minutes between news broadcasts |
+| `news_count` | 1 | per-channel | Headlines per broadcast cycle |
+| `quotes_interval` | 60 | per-channel | Minutes between quote auto-posts |
+
+## Config file keys
+
+| Key | Description |
+|-----|-------------|
+| `[jeeves] db_path` | Path to main JSON database |
+| `[jeeves] duck_db_path` | Path to duck scores SQLite database |
+| `[jeeves] recipes_path` | Path to recipes JSON file |
+| `[respond] keywords` | Newline-separated trigger words for keyword responses |
+| `[respond] responses` | Newline-separated response lines (random choice) |