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

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

docs/getting-started.md

@@ -0,0 +1,118 @@
+# Getting started
+
+This page takes you from nothing to a bot running on your machine.
+
+## Requirements
+
+- **Go**: the version in `go.mod` (the Dockerfile builds with the same one).
+- **PostgreSQL 16 or newer**: the included `docker-compose.yml` starts one for you.
+- **A Discord application** with a bot user (see below).
+- Optional: [Air](https://github.com/air-verse/air) for live reload, [Just](https://github.com/casey/just) for shortcuts, and a [Lavalink](https://github.com/lavalink-devs/Lavalink) server if you want music.
+
+## 1. Create the Discord application
+
+1. Open the [Discord developer portal](https://discord.com/developers/applications) and create an application. Copy its **Application ID**: this is `APP_ID`.
+2. Under **Bot**, create the bot user and copy its token: this is `BOT_TOKEN`. Keep it secret.
+3. Under **Bot**, switch on these **privileged gateway intents**: **Server Members Intent** (welcome messages, security) and **Message Content Intent** (leveling and spam detection). The bot also uses the non-privileged Guilds, Guild Moderation (bans and the audit log), Guild Messages, Guild Voice States and Direct Messages intents. You do not need to enable those by hand.
+4. Invite the bot with the `bot` and `applications.commands` scopes. It needs these permissions, depending on which modules you use:
+
+   | Permission | Used by |
+   | --- | --- |
+   | View Channels, Send Messages, Embed Links, Attach Files | everything that posts, ticket transcripts |
+   | Read Message History, Manage Messages | moderation purge, spam heat |
+   | Manage Roles | default role, level rewards, quarantine |
+   | Manage Channels | lockdown, slowmode, meeting rooms, snapshot restore |
+   | Manage Server | pausing invites during a raid |
+   | Kick Members, Ban Members, Moderate Members | moderation commands, Join Gate, raid mode, anti-nuke |
+   | View Audit Log | anti-nuke, unauthorised bot detection |
+   | Create Private Threads, Send Messages in Threads, Manage Threads | tickets |
+   | Connect, Speak, Move Members | music, meeting rooms |
+
+   The bot's role must sit **above** the roles it manages or protects against. Discord does not let a bot change members whose highest role is higher than its own.
+
+## 2. Configure the environment
+
+The bot reads environment variables, and loads a `.env` file from the working directory if there is one (`internal/config/config.go`).
+
+| Variable | Required | Meaning |
+| --- | --- | --- |
+| `BOT_TOKEN` | yes | The bot token. |
+| `APP_ID` | yes | The application ID. |
+| `GUILD_ID` | no | If set, slash commands are registered in this server only, and appear within seconds. If empty they are registered globally, which Discord can take up to an hour to show. Use a test server while developing. |
+| `DB_HOST` | yes | A pgx connection string, for example `postgres://velox:velox_pwd@localhost:5432/velox?sslmode=disable`. |
+| `TWITCH_CLIENT_ID` | yes | A Twitch client ID, used to check who is live. The bot refuses to start without it, even if you never use Twitch alerts. Any non-empty value works if you do not use them. |
+| `LAVALINK_HOST` | no | Lavalink address, for example `ws://localhost:2333`. Leave empty to run without music. |
+| `LAVALINK_PASSWORD` | no | Lavalink password. |
+
+A minimal `.env` for local development:
+
+```bash
+BOT_TOKEN=your-bot-token
+APP_ID=123456789012345678
+GUILD_ID=123456789012345678
+DB_HOST=postgres://velox:velox_pwd@localhost:5432/velox?sslmode=disable
+TWITCH_CLIENT_ID=unused
+```
+
+`.env` is ignored by git. Never commit it.
+
+Who the beta testers are is **not** an environment variable. It is set on the dashboard and stored in the database. See [Beta features](beta-features.md).
+
+## 3. Set up the database
+
+Start PostgreSQL with Compose:
+
+```bash
+docker compose up -d db
+```
+
+Then load the schema:
+
+```bash
+psql "postgres://velox:velox_pwd@localhost:5432/velox?sslmode=disable" -f schema.sql
+```
+
+`schema.sql` is written with `CREATE TABLE IF NOT EXISTS`, so running it again is safe. It is a mirror of the tables the bot uses. If you run the dashboard API as well, the API's migrations create and change these tables, and you do not need `schema.sql` at all. Read [Database](database.md) before changing a table.
+
+## 4. Run
+
+```bash
+go run .
+```
+
+You should see the bot connect, and the slash commands appear in your test server. Type `/ping`.
+
+With live reload:
+
+```bash
+air
+```
+
+With Just (`Justfile`):
+
+```bash
+just up      # start PostgreSQL
+just start   # start PostgreSQL and run Air
+just down    # stop PostgreSQL
+```
+
+## 5. Turn modules on
+
+Nothing is on by default. In your server:
+
+- `/security toggle` to enable Join Gate, raid mode, anti-nuke or heat.
+- `/tickets setup`, then `/tickets category add` and `/tickets panel`.
+- `/slvl toggle` for leveling.
+- `/config setlogchannel` and `/config enablelogging` for logs.
+- `/music toggle` for music (needs Lavalink).
+
+The [Features](features.md) page explains each module, and the [Command reference](commands.md) lists every option.
+
+## Optional: music with Lavalink
+
+Music needs a running Lavalink server and `LAVALINK_HOST` / `LAVALINK_PASSWORD`. Without them the bot starts normally and music simply does not work. Members need a role named exactly **DJ** to use `/play`, `/queue` and `/volume`.
+
+## Next steps
+
+- Running it for real: [Deployment](deployment.md).
+- Changing or adding things: [Development guide](development.md).