Docs: wiki-style documentation in docs/, README as the front page

Co-Authored-By: Claude Sonnet 5.5 <[email protected]>

docs/troubleshooting.md

@@ -0,0 +1,57 @@
+# Troubleshooting
+
+## The bot does not start
+
+| Message | Cause |
+| --- | --- |
+| `BOT_TOKEN is not set`, `APP_ID is not set`, `DB_HOST is not set` | A required variable is missing. See [Getting started](getting-started.md#2-configure-the-environment). |
+| `TWITCH_CLIENT_ID is not set` | It is required even if you do not use Twitch alerts. Set any non-empty value. |
+| `Error creating database` | `DB_HOST` is wrong, or PostgreSQL is not running or not reachable. Try the connection string with `psql`. |
+| `Error starting bot` | The token is wrong, or a privileged intent is not enabled in the developer portal. |
+| `Disallowed intents` | Enable **Server Members Intent** and **Message Content Intent** in the developer portal, under Bot. |
+
+## Slash commands do not appear
+
+- With `GUILD_ID` set, commands appear in that server within seconds. If it is empty they are global and can take up to an hour.
+- The bot must be invited with the `applications.commands` scope.
+- If a command is defined but not in the `handlers` map in `internal/commands/commands.go`, it shows up and does nothing.
+- If the bot logs `Cannot create '<name>' command`, read the error. A name or description that is too long, or an invalid option, makes Discord reject that one command.
+- Commands that you removed from the code stay in Discord until you delete them (in the developer portal or through the API).
+
+## A command says "You don't have permission"
+
+Many commands need **Manage Server** (see the [Command reference](commands.md)), and the music commands need a role called exactly **DJ**. Security actions such as turning protection off need the **server owner or a trusted user**, whatever permissions you have.
+
+## The bot cannot do something in a server
+
+Most failures are about the bot's role:
+
+- The bot's role must be **above** the roles it manages and the members it moderates or quarantines.
+- It needs the permissions listed in [Getting started](getting-started.md#1-create-the-discord-application). Check the channel's own permission overrides too: a channel can deny what the server role allows.
+- Security messages say "Check that Velox's role is high enough and has the permissions it needs" for this reason.
+
+## Music does not play
+
+- `LAVALINK_HOST` and `LAVALINK_PASSWORD` must match your Lavalink server, and Lavalink must be running and reachable from the bot (in Compose, use the service name, not `localhost`).
+- You need the **DJ** role.
+- A server admin can turn music off with `/music toggle`.
+
+## Level-ups, logs or welcome messages do nothing
+
+They are off until enabled: `/slvl toggle`, `/config enablelogging` with `/config setlogchannel`, and `/config setwelcomechannel`. Leveling and spam detection read message text, so the **Message Content Intent** must be on. Welcome messages and security need the **Server Members Intent**.
+
+## Dashboard actions have no effect
+
+The dashboard talks to the bot through the database (see [Database](database.md#dashboard-to-bot-settings-and-requests)).
+
+- Check that the bot and the API use the **same database**.
+- For a request such as skipping a song or ending a raid, look in the matching `*_commands` table. A row with an empty `processed_at` is waiting. If many are waiting, the bot's listener is down: look for `command listener stopped` in its log. It reconnects every 10 seconds.
+- Settings are read when needed and may be cached briefly (the beta settings are polled every 30 seconds).
+
+## Beta features are not available to a tester
+
+Go through [Beta features](beta-features.md): is the Beta Tester role chosen on the dashboard? Is the person in the beta server, and do they have the role? Has 30 seconds passed? `/beta` (owner only) shows how access is set up.
+
+## Getting more detail
+
+The bot logs to standard output. Run `docker compose logs -f bot`, or just `go run .`, and reproduce the problem. Errors from Discord calls are logged with the server and channel IDs involved.