first commit

README.md

@@ -0,0 +1,61 @@
+# Cycling Discord Bot
+
+A Discord bot for tracking cycling (and other fitness) distances across a server. Members post their distance in a designated channel and the bot logs it automatically.
+
+## Features
+
+- Auto-parses distances from messages in a configured channel
+- Leaderboard, yearly totals, weekly/monthly reports
+- Personal stats: history, PB, streaks, unit preference (km/miles)
+- Social: kudos, head-to-head comparison
+- Admin tools: manual adjustments, ride removal, audit log, challenge management
+- Updates channel topic with the current running total
+
+## Setup
+
+Copy `.env.example` to `.env` and fill in your values:
+
+```
+DISCORD_TOKEN=your-bot-token-here
+GUILD_ID=                   # optional: restrict to one server for instant command propagation
+DB_PATH=cycling_bot.db      # optional: defaults to cycling_bot.db
+```
+
+## Build & Run
+
+```sh
+go build -o cycling-bot .
+./cycling-bot
+```
+
+Cross-compile for FreeBSD:
+
+```sh
+GOOS=freebsd GOARCH=amd64 go build -o cycling-bot .
+```
+
+See `Makefile` for deploy targets (`make deploy`, `make deploy-env`, `make restart`, etc.).
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/setchannel` | [Admin] Set the channel to track |
+| `/resetchallenge` | [Admin] Archive current totals and start fresh |
+| `/setchallengename` | [Admin] Name the current challenge |
+| `/setgoal` | [Admin] Set a collective KM goal |
+| `/addkm` | [Admin] Manually credit/debit KM for a user |
+| `/removelog` | [Admin] Remove a ride by message ID |
+| `/audit` | [Admin] View all logged rides for a user |
+| `/leaderboard` | Top cyclists in the current challenge |
+| `/yearlyleaderboard` | Top cyclists for the calendar year |
+| `/totalkm` | Total distance in the current challenge |
+| `/mystats` | Your challenge + yearly stats |
+| `/history` | Your recent rides |
+| `/pb` | Your personal best single ride |
+| `/streak` | Consecutive days with a logged ride |
+| `/setunit` | Set preferred unit (km or miles) |
+| `/kudos` | Give a shoutout to another rider |
+| `/compare` | Head-to-head stats vs another rider |
+| `/weeklyreport` | Distances logged this week |
+| `/monthlyreport` | Distances logged this month |