init: mostly vibed

1 files changed, 55 insertions, 0 deletions

diff --git a/docs/daffy.md b/docs/daffy.md
new file mode 100644
index 0000000..d9a8311
--- /dev/null
+++ b/docs/daffy.md
@@ -0,0 +1,55 @@
+# daffy
+
+Duck hunting game bot. Ducks appear at random intervals; players race to shoot
+them. Scores are stored in SQLite. The hunt auto-stops after a configurable
+number of rounds with no participants.
+
+## Dependencies
+
+No external libraries required.
+
+## Commands
+
+### Game (anyone in channel)
+| 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 (owner/op) |
+
+Owner can also use `!score clear all` or `!score clear #channel` from PM.
+
+### Hunt control (owner / op)
+| Command | Description |
+|---------|-------------|
+| `!hunt` | Show hunt state (on/off/active, idle counter) |
+| `!hunt start` | Start the hunt |
+| `!hunt stop` | Stop the hunt |
+| `!hunt idle <N>` | Set empty-round auto-stop threshold (0 = never); takes effect immediately if threshold is already met |
+
+### Admin (owner)
+| Command | Description |
+|---------|-------------|
+| `!join #channel` | Join a channel |
+| `!part [#channel]` | Leave a channel |
+| `!chans` | List channels |
+| `!help` | Show usage (PM) |
+
+## How it works
+
+- A duck spawns every `spawn_min` to `spawn_max` seconds (random, default 1-5 minutes).
+- First player to `!bang` scores a point. Each player has one shell; use `!reload` to reload.
+- `!bang` and `!reload` are ignored while the hunt is off.
+- If no one shoots within `flee_time` seconds (default 45), the duck flees and the round is marked empty.
+- After `idle_rounds` consecutive empty rounds the hunt auto-stops.
+
+## Config keys
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `[daffy] db_path` | `~/daffy_scores.db` | Path to SQLite scores database |
+| `[daffy] idle_rounds` | 3 | Empty rounds before auto-stop (0 = never) |
+| `[daffy] spawn_min` | 60 | Minimum seconds between duck spawns |
+| `[daffy] spawn_max` | 300 | Maximum seconds between duck spawns |
+| `[daffy] flee_time` | 45 | Seconds before an unshot duck flees |