Documentation updates

README.md

@@ -1,48 +1,29 @@
-# python-app-rocketbot
+# Rocketbot
 
-Experimental Discord bot written in Python.
+Discord bot for detecting and dealing with jerks. This bot is Rocketsoup's fault.
 
 ## Requirements
 
-* Written for Python 3.9
-* Install dependencies with `pip3.9 install -r requirements.txt`
+* Python 3.9
+
+## Setup
+
+See main document, [docs/setup.md](Setup).
+
+In brief, the full setup process is:
+- create a Discord application in their developer portal
+- configure a `config.py`
+- install Python dependencies
+- run the `bot.py` script
+- invite the bot to your server
+- do additional configuration for your guild using chat commands
 
 ## Usage
 
+See main document, [docs/commands.md](Commands).
+
 * To see the list of commands, type `$rb_help`.
 * To get help on a specific command, type `$rb_help commandname` (don't prefix the command name you want help on). E.g. `$rb_help hello`.
 * To get help on a command group, type `$rb_help groupname`. E.g. `$rb_help config`.
 * To get help on a subcommand in a group, type `$rb_help groupname commandname`. E.g. `$rb_help config setwarningchannel`.
 * To see if the bot is alive, type `$rb_hello`.
-* Other commands are too numerous and always changing to document here, so see `$rb_help` for more.
-
-## Setup
-
-Currently the bot is just run in the console locally. It blocks until Ctrl+C is
-pressed. Before running, you must copy config.py.sample to config.py and fill
-in the "client_token" value. To get a token, visit
-https://discord.com/developers/applications and create an application. Then
-create a bot for the application and enable the "server members intent". Click
-the "copy" button in the "token" section near the top and paste this value into
-config.py's "client_token" attribute.
-
-Create a "config" subdirectory under your source folder. This is where guild-specific configuration is written as JSON files.
-
-To start, run `python3 bot.py`. Then visit
-https://discord.com/oauth2/authorize?client_id=[application_id]&scope=bot&permissions=395204357318,
-where [application_id] is the "application id" value on your app configuration
-"general information" page. Once invited, test if the bot is working by typing
-`$rb_hello` in your Discord server.
-
-Once running, you should immediately set up a warning channel and optionally a
-user/role to tag in warning messages. Go to a channel you want warnings to be
-posted (typically a channel the general userbase cannot see) and type
-`$rb_config setwarningchannel`. This will set that channel as the destination
-for warnings about suspicious behavior on the server. To have these messages
-tag a user or role (such as `@Mods`), type `$rb_config setwarningmention @userorrole`.
-This must be an actual autocompleted @ mention that shows up in a different
-color, not just the name of the user/role. Otherwise warning messages will
-be prefixed with that plaintext name, not with an actual @. To mention several
-people or roles, enclose the whole list in double quotes. E.g.
-`$rb_config setwarningmention "@Mod @Admin"`. You can test out this configuration
-by entering `$rb_testwarn` to issue a test warning.

docs/commands.md

@@ -0,0 +1,278 @@
+# Commands
+
+Rocketbot's functionality is broken into different functional areas that
+typically have a master switch to enable/disable it and some other configuration.
+Configuration is specific to each server the bot is invited to.
+
+For all the examples here, I'm assuming the default command prefix of `$rb_`.
+If you set a different one in `config.py`, translate accordingly.
+
+## Log channel
+
+The first thing you'll want to do is configure a channel where bot messages
+can go. This should be a channel only mods can see. Go into that channel and
+type
+
+```
+$rb_config setwarningchannel
+```
+
+This ensures warnings will go somewhere appropriate.
+
+You will probably also want to set a role to tag for important warnings to get
+their attention. E.g. to tag the `@Mod` role type
+
+```
+$rb_config setwarningmention @Mod
+```
+
+Entering that will configure who to mention, and it will also mention them right
+now in that message you just typed. Apologize to all the mods who you just
+bothered and explain you were just configuring a cool new bot.
+
+## Help!!
+
+I don't remember the commands for my own bot, so I don't expect you will either.
+The only thing you need to remember is `$rb_help`. The bot will reply with a
+summary of all the top-level commands available. As an example:
+
+```
+Auto Kick:
+  autokick       Automatically kicks all new users as soon as they join
+Configuration:
+  config         Manages general bot configuration
+Crosspost Detection:
+  crosspost      Manages crosspost detection and handling
+General:
+  deletemessages Mass deletes messages
+  hello          Simple test reply
+  shutdown       Shuts down the bot
+  testwarn       Posts a test warning
+Join Age:
+  joinage        Tracks recently joined users with options to mass kick or ban
+Join Raids:
+  joinraid       Manages join raid detection and handling
+Logging:
+  logging        Manages event logging
+Pattern Matching:
+  pattern        Manages message pattern matching
+URL Spam:
+  urlspam        Manages URL spam detection
+Username Pattern:
+  username       Manages username pattern detection
+No Category:
+  help           Shows this message
+
+Type $rb_help command for more info on a command.
+You can also type $rb_help category for more info on a category.
+```
+
+Each section is known internally as a "cog". If you're mucking around in the code,
+each cog is its own source file in the `rocketbot/cogs` directory. But you can
+just think of them as categories. Some of these are commands of their own (e.g.
+`hello`, invoked with `$rb_hello`) but most have subcommands. You can find out
+more using `$rb_help commandname`, e.g. `$rb_help config` will show subcommands for
+config.
+
+```
+$rb_config
+
+General guild configuration command group
+
+Commands:
+  getwarningchannel Shows the mod warning channel
+  getwarningmention Shows the user/role to mention in warning messages
+  setwarningchannel Sets the mod warning channel
+  setwarningmention Sets a user/role to mention in warning messages
+
+Type $rb_help command for more info on a command.
+You can also type $rb_help category for more info on a category.
+```
+
+And then you can invoke a subcommand with `$rb_commandname subcommandname`. e.g.
+`$rb_config setwarningchannel`. To get more info about a subcommand, use `$rb_help`
+again. e.g. `$rb_help config setwarningchannel`.
+
+## Cogs
+
+This section goes through each cog, what it does, and how to use it.
+
+### Autokick
+
+Autokick is a feature of last resort, a sort of lockdown mode that immediately
+kicks all new users who join. (Users who joined before enabling this are fine.)
+We have on one occasion had some kind of bot that was doing tons and tons of
+joins, and there was no other way to stop them. Obviously something you want to
+supervise and disable as soon as the threat has passed.
+
+Subcommands
+- `enable`/`disable` - Toggle autokicking
+- `getbancount`/`setbancount` - If the same person keeps rejoining after being
+    kicked, ban them after this many rejoins.
+- `getofflineonly`/`setofflineonly` - Whether to only kick users who join with
+    a status of offline. That's not impossible in ordinary use, but it's
+    suspect and likely indicative of bots versus real users.
+
+### Config
+
+General config that isn't specific to one cog.
+
+Subcommands
+- `getwarningchannel`/`setwarningchannel` - Determines the channel where log
+    messages are posted. Setting the warning channel doesn't take an argument; it
+    uses the current channel you typed the command in.
+- `getwarningmention`/`setwarningmention` - The user or role you want tagged when
+    the bot needs to alert someone of suspicious activity. Needs to be a proper
+    autocompleted @ mention, not just the name.
+
+### Crosspost detection
+
+Detects an extremely common pattern we see of someone joining and copy/pasting
+the exact same message in as many channels as possible. This cog will look at
+recent messages from a user and see which ones contain the exact same text in
+multiple channels, and if it exceeds the configured number within the configured
+time span, it's ban hammer time.
+
+Subcommands
+- `enable`/`disable` - Master toggle for this entire feature.
+- `getwarncount`/`setwarncount` - How many duplicate messages will cause a
+    warning message to be posted that alerts the mods.
+- `getbancount`/`setbancount` - How many duplicate messages should result in an
+    automatic ban. Should be greater than the warning count.
+- `gettimespan`/`settimespan` - Sets the time window within which to look for
+    duplicates. Value is in seconds. Spammers usually fire these off very quickly,
+    so a minute or less is more than enough.
+- `getminlength`/`setminlength` - For text-only messages, sets the minimum length
+    to be considered for duplicate detection. Maybe a benign (but annoying) user
+    posts "lol" at everything in multiple channels. Use this to filter for that
+    case.
+
+### General
+
+These are just general top-level commands, not subcommands.
+
+Commands
+- `deletemessages <@user> <timespan>` - Manually deletes a bunch of messages by a
+    particular user. Useful if you banned but accidentally forgot to delete
+    recent history, or to clean up after someone had a bit of a manic posting
+    spree. The timespan is a value like "30s" for 30 seconds, "5m" for 5
+    minutes, or "1h30m" for an hour and a half. NOTE: This only works for fairly
+    recent messages. You can't use it to delete things posted way back in the
+    scrollback.
+- `hello` - Just for testing bot responsiveness. Or a desperate need to be seen.
+- `shutdown` - Terminates the bot. I forgot this was here. I've never needed it.
+    If somehow the bot goes rogue and you're not there to ctrl+C it, use this.
+- `testwarn` - Posts a test mod warning in the configured warning channel with
+    the configured mention user/role.
+
+### Join age
+
+This cog isn't really needed any more since the Members tab was added to Discord.
+It's used for seeing who joined most recently. The list of recent joins is only
+kept in memory, and it keeps a limited number, so it's really only useful for
+the past few days.
+
+Subcommands
+- `enable`/`disable` - Toggle join tracking.
+- `getjointime`/`setjointime` - How long to track a join, in seconds.
+- `search <timespan>` - Shows all users who joined in the last x length of time.
+    Values are like `30s` for 30 seconds, `5m` for 5 minutes, `1h30m` for an hour
+    and a half, etc.
+
+### Join raids
+
+While not as common in the past year or two, we used to get a suspicious number
+of users all joining in very close succession with no obvious cause, followed
+by users being spammed in DMs by them. This cog attempts to alert us to such
+spikes in joins.
+
+Subcommands
+- `enable`/`disable` - Toggle the feature.
+- `getjoincount`/`setjoincount` - Sets the minimum number of suspicious joins.
+- `getjointime`/`setjointime` - Sets the span of time that number of joins must
+    occur to be suspicious, in seconds.
+
+### Logging
+
+We found it valuable to log certain events, namely message edits and deletions,
+due to some users frequently saying something questionable and then covering
+their tracks. We used to use another bot to do that until it silently just
+decided to stop being maintained. Thanks. So this cog attempts to reproduce
+that, logging as many meaningful events as possible.
+
+Subcommands
+- `enable`/`disable` - You get the full firehose or you get nothing.
+
+### Patterns
+
+This is the most flexible cog. It can match arbitrary messages with complex
+criteria and take a number of automatic actions on them. The full syntax is kind
+of complex and is detailed in its [own document](patterns.md).
+
+Subcommands
+- `add ...` - Adds a new pattern to look for (see [Patterns](patterns.md)).
+- `remove <name>` - Removes a previously added pattern by name.
+- `list` - Show all configured patterns.
+- `setpriority <name> <priority>` - Alters the priority of a pattern. The
+    priority is a unitless value used to pick which pattern wins if a message
+    matches more than one. Patterns without priorities set have a default value
+    of 100. The highest value wins.
+
+### URL spam
+
+This cog detects two kinds of suspicious link post behaviors.
+
+The first is posting a link suspiciously soon after joining. Honestly, this has
+had a pretty low hit rate. Join age seems unreliable. Supposedly, Discord
+imposes a 10m cooldown after joining a server before you can post, but I've
+seen people post within the first minute. And they are usually benign, like a
+reaction GIF or relevant Twitch clip. While the actual spammers don't seem to
+get flagged, as they seem to use accounts that have been lying in wait a long
+time. YMMV.
+
+The second is deceptive links. Discord added the ability in 2024 or 25 to change
+the text of a link instead of it always just showing the URL using the markdown
+syntax `[link text](https://urlhere)` which shows up as "link text" in blue.
+While Discord does warn users whenever they click a link where the text isn't
+exactly the same as the URL, this happens in benign circumstances often enough
+that users may ignore it. Discord prevents posting mismatching URLs like
+`[https://goodsite.com](https://badsite.com)`, however it doesn't prevent posting
+things that are URL-like, like `[goodsite.com](https://badsite.com)` (without
+the `https://`). Our deceptive link detection catches these URL-like link labels.
+
+Subcommands
+- `enable`/`disable` - Toggle the feature.
+- `getjoinage`/`setjoinage` - Sets the length of time after joining when posted
+    links are considered suspicious, in seconds.
+- `getaction`/`setaction` - Action to take when a join age link is detected.
+    One of these values:
+    - `nothing` - Ignore
+    - `modwarn` - Post a warning message in the log channel and tag mods.
+    - `delete` - Delete the message.
+    - `kick` - Kick the user.
+    - `ban` - Ban the user.
+- `getdeceptiveaction`/`setdeceptiveaction` - Action to take when a deceptive
+    link is detected. One of these values:
+    - `nothing` - Ignore
+    - `modwarn` - Post a warning message in the log channel and tag mods.
+    - `modwarndelete` - Post a mod warning message and delete the message.
+    - `chatwarn` - Reply to the message in the same channel calling out the
+        suspicious link.
+    - `chatwarndelete` - Reply to the message and delete it.
+    - `delete` - Delete the message.
+    - `kick` - Kick the user.
+    - `ban` - Ban the user.
+
+### Username patterns
+
+Notifies us when users with certain usernames join a server. Problem users will
+often get banned and just create another similarly named account, so this
+helps us catch ban evasion. When a matching username joins the server, a mod
+warning message will be posted in the log channel. The pattern is just a simple
+substring matched case-insensitively.
+
+Subcommands
+- `enable`/`disable` - Toggle the feature.
+- `add <pattern>` - Adds a substring to look for in usernames of newly joined members.
+- `remove <pattern>` - Removes a pattern.
+- `list` - Lists all tracked patterns.

patterns.md → docs/patterns.md

@@ -1,28 +1,39 @@
 # Patterns
 
-The PatternCog offers a way of creating custom message filters of moderate complexity without needing to make code changes in the bot and redeploy it. A guild can have any number of custom patterns. The commands are:
+The PatternCog offers a way of creating custom message filters of moderate
+complexity without needing to make code changes in the bot and redeploy it. A
+guild can have any number of custom patterns. The commands are:
 
 * `$rb_pattern add <name> <statement>` - Add a new named pattern
 * `$rb_pattern remove <name>` - Remove a named pattern
 * `$rb_pattern list` - List all named patterns
 
-The pattern `<name>` can be anything. If it contains spaces, enclose it in double quotes, e.g. `"my filter"`.
+The pattern `<name>` can be anything. If it contains spaces, enclose it in
+double quotes, e.g. `"my filter"`.
 
 ## Statements
 
-A statement consists of one or more actions to take on a message followed by an expression defining the criteria for which messages match. For example:
+A statement consists of one or more actions to take on a message followed by an
+expression defining the criteria for which messages match. For example:
 
 ```
 reply "You can't say that word!", delete if message contains "heck"
 ```
 
-This statement has two actions: replying, then deleting the original message. It will match any message that contains the word "heck".
+This statement has two actions (separated by a comma): replying, then deleting
+the original message. It will match any message that contains the word "heck".
 
-The list of actions and the matching expression are separated by the word "if", which must be present in every statement.
+The list of actions and the matching expression are separated by the word "if",
+which must be present in every statement.
+
+```
+<action>, <action>, ..., <action> if <condition>
+```
 
 ### Actions
 
-One or more actions can be added to the statement. If there is more than one, they are separated with commas. Example:
+One or more actions can be added to the statement. If there is more than one,
+they are separated with commas. Example:
 
 ```
 delete, kick, modwarn
@@ -33,13 +44,20 @@ Available actions:
 * `ban` - Bans the user. The "reason" in the audit log will reference the pattern name.
 * `delete` - Deletes the message.
 * `kick` - Kicks the user. The "reason" in the audit log will reference the pattern name.
-* `modinfo` - Posts an informative message in the bot warning channel but does not tag the mods. Useful for logging a pattern that is mildly harmful but not worth getting immediate mod attention. Message will have reactions to delete, kick, or ban.
-* `modwarn` - Tags the mods in a warning message. The message will offer quick actions to manually delete the message, kick the user, and ban the user (assuming the other actions didn't already do one or more of these things)
-* `reply "message"` - Makes Rocketbot automatically reply to their message with the given text.
+* `modinfo` - Posts an informative message in the bot warning channel but does
+    not tag the mods. Useful for logging a pattern that is mildly harmful but
+    not worth getting immediate mod attention. Message will have options to
+    delete, kick, or ban.
+* `modwarn` - Tags the mods in a warning message. The message will offer quick
+    actions to manually delete the message, kick the user, and ban the user
+    (assuming the other actions didn't already do one or more of these things)
+* `reply "message"` - Makes Rocketbot automatically reply to their message with
+    the given text.
 
 ### Expressions
 
-The simplest expression just consists of a message field, a comparison operator, and a value to compare it to. For example:
+The simplest expression just consists of a message field, a comparison operator,
+and a value to compare it to. For example:
 
 ```
 content.plain contains "forbidden"
@@ -51,13 +69,28 @@ The available operators and type of value depends on the field being accessed.
 
 #### Fields
 
-* `author` - Who sent the message. Available operators: `==`, `!=`. Comparison value must be a user mention (an @ that Discord will tab-complete for you).
-* `author.id` - The numeric ID of the user who sent the message. Available operators: `==`, `!=`. Comparison value must be a numeric user ID.
-* `author.joinage` - How much time has elapsed from when the author joined and when the message was sent. If the user has joined and left multiple times this is the most recent join time. Available operators: `==`, `!=`, `<`, `>`, `<=`, `>=`. Comparison value must be a timespan (see below)
-* `author.name` - The username of the author. Available operators: `==`, `!=`, `contains`, `!contains`, `containsword`, `!containsword`, `matches`, `!matches`. Comparison value must be a quoted string.
-* `content.plain` - The plain text of the message. All markdown formatting is removed, and mentions look like the `@Username` text name that gets displayed.
-* `content.markdown` - The raw markdown of the message. This contains all markdown characters, and mentions are of the `<@!0000000>` form. Available operators: `==`, `!=`, `contains`, `!contains`, `matches`, `!matches`. Comparison value must be a quoted string.
-* `lastmatched` - How long ago this pattern matched a message. Used for imposing a cooldown, especially for autoresponses. If the pattern has never matched it will be treated as if it last ran 100 years ago for comparison purposes. Available operators: `==`, `!=`, `<`, `>`, `<=`, `>=`. Comparison value must be a timespan (see below).
+* `author` - Who sent the message. Available operators: `==`, `!=`. Comparison
+    value must be a user mention (an @ that Discord will tab-complete for you).
+* `author.id` (alias `author`) - The numeric ID of the user who sent the message. Available
+    operators: `==`, `!=`. Comparison value must be a numeric user ID.
+* `author.joinage` - How much time has elapsed from when the author joined and
+    when the message was sent. If the user has joined and left multiple times
+    this is since the most recent join. Available operators: `==`, `!=`, `<`,
+    `>`, `<=`, `>=`. Comparison value must be a timespan (see below)
+* `author.name` - The username of the author. Available operators: `==`, `!=`,
+    `contains`, `!contains`, `containsword`, `!containsword`, `matches`,
+    `!matches`. Comparison value must be a quoted string.
+* `content.plain` - The plain text of the message. All markdown formatting is
+    removed, and mentions look like the `@Username` text name that gets displayed.
+* `content.markdown` (alias `content`) - The raw markdown of
+    the message. This contains all markdown characters, and mentions are of the
+    `<@!0000000>` form. Available operators: `==`, `!=`, `contains`, `!contains`,
+    `matches`, `!matches`. Comparison value must be a quoted string.
+* `lastmatched` - How long ago this pattern matched a message. Used for imposing
+    a cooldown, especially for autoresponses. If the pattern has never matched
+    it will be treated as if it last ran 100 years ago for comparison purposes.
+    Available operators: `==`, `!=`, `<`, `>`, `<=`, `>=`. Comparison value must
+    be a timespan (see below).
 
 #### Operators
 
@@ -140,7 +173,7 @@ $rb_pattern add "lunch" reply "Lunch is at noon." if content.plain == "When is l
 
 `<ws>` ::= SPACE | TAB | CR | LF | `<ws>` `<ws>`
 
-`<actions>` ::= `<action>` | `<action>` `<ws>` `<actions>`
+`<actions>` ::= `<action>` | `<action>` "," `<ws>` `<actions>`
 
 `<action>` ::= "ban" | "delete" | "kick" | "modinfo" | "modwarn" | "reply" `<ws>` `<quoted_string>`
 

docs/setup.md

@@ -0,0 +1,133 @@
+# Setup
+
+## Make Discord application
+
+A Discord application is the record in Discord's servers about your bot. An
+application can be a lot of things, not just bots, but we only care about bots.
+You can think of it sort of like the bot's Discord account but with more nerdy
+settings. When you run the bot script, it will authenticate as this application
+and assume the identify of the bot user in Discord. Authentication is done via
+a client token, discussed more later.
+
+Rocketsoup is currently running the bot under an application entry he created
+under his own account, and running the bot script in a terminal on his own computer.
+Professional! If someone will be taking over the bot, they'll likely want to
+create their own application under their own account (or a shared account perhaps).
+
+The application portal can be found here: https://discord.com/developers/applications
+Click "New Application" and give it a name, e.g. Rocketbot. Then click into it
+to see its settings. It's been a while since I set this up, and things are
+always changing, but settings of note:
+- **General Information > App Icon** - You can use this or some other 1024x1024 image:
+    [icon.png](icon.png). This is what shows up when inviting the bot to a server.
+- **General Information > Application ID** - Take note of this. You'll need it later.
+- **Installation > Installation Contexts** - Enable "Guild Install", disable "User Install"
+- **Bot > Icon** - Same image as the App Icon above. This is what actually shows
+    as the bot's avatar in Discord.
+- **Bot > Username** - What the bot shows up as in Discord.
+- **Bot > Token** - ⚠️ IMPORTANT. This is the client token to authenticate the
+    bot. It needs to be filled in the config. You will only be shown the value
+    ONCE!! So store it somewhere safe, like a password manager! If you lose it
+    you can create a new one. More below on what to do with this value.
+- **Bot > Privileged Gateway Intents** - These give the bot broad categories of
+    privileges for certain kinds of data. Since Rocketbot is pretty broad in its
+    functionality, it needs a lot. Enable:
+    - **Presence Intent** - For tracking joins/leaves, I think
+    - **Server Members Intent** - For getting member info
+    - **Message Content Intent** - To be able to get the text and other details about messages
+
+> [!TIP]
+> It can be useful to set up a second application specifically for testing.
+> e.g. I have a "Rocketbot Test" application, configured exactly the same as
+> the production application, but it can be in a completely independent
+> list of servers for testing and can run at the same time as the production
+> one.
+
+## Configure bot script
+
+The bot relies on `config.py` for its general configuration. (Settings for each
+individual guild are stored elsewhere; more on that later.) You'll want to rename
+or copy `config.sample.py` to `config.py` and open it in an editor. The file
+consists of a single `CONFIG` dict.
+
+The most essential value to set is `CONFIG.client_token`. The client token you got
+above in the Discord application portal that you _definitely stored in a safe
+place like I told you_ is what you want to paste here.
+
+You may also want to set `CONFIG.config_path`. In retrospect, that's confusing
+naming. Anyway, it's the path to a directory where guild-specific settings will
+be stored. It can be wherever makes sense to you. I just store em in a `config`
+subdirectory in the project itself. That's probably a bad idea for reasons I'm
+too bad a programmer to know about. Store 'em wherever you want. (These guild
+setting files are a good candidate for timely backups, btw, if that influences
+your choice. Maybe a synced cloud folder?)
+
+If you'd like, you can also change the command prefix. The bot recognizes commands
+by looking for messages that start with this prefix. E.g. if the prefix is `$rb_`
+(the default) then typing the message `$rb_help` will invoke the `help` command
+and respond with a list of other commands.
+
+## Run the script
+
+I wrote this for Python 3.9, and its only dependency is the Discord.py library.
+I am bad at Python, so use these instructions only until a grown up programmer
+can be found to give you better ones. I'm on Mac, so apologies for any inadvertent
+Mac-specificness. Linux will be similar. Windows probably won't be as similar.
+
+1. Set up a virtual environment and install dependencies (only need to do this once)
+    ```shell
+    python3.9 -m venv .venv
+    source .venv/bin/activate
+    pip install -r requirements.txt
+    ```
+2. Run the bot
+    ```shell
+    source .venv/bin/activate   # skip if you already just did it above
+    python bot.py
+    ```
+
+It will take a few seconds to connect and when you see output like this it means
+it's ready and listening for things to happen.
+
+```
+[2025-12-11T16:30:51|-|-] Bot initializing...
+[2025-12-11T16:30:51|-|-] Type $rb_help in Discord for available commands.
+[2025-12-11T16:30:52|GeneralCog|-] Connected
+[2025-12-11T16:30:54|GeneralCog|-] Bot done initializing
+----------------------------------------------------------
+```
+
+Leave it running and, I dunno, minimize the window or something. You can see
+events logged here as they come up. If you wanna stop the bot, just hit ctrl+C.
+
+## Invite bot to your server
+
+You can invite the bot to your server by constructing a link like so:
+```
+https://discord.com/oauth2/authorize?client_id=APPIDHERE&scope=bot&permissions=4290289506188502
+```
+The `APPIDHERE` is the value in the application portal under General Information >
+Application ID. ⚠️IMPORTANT: It is NOT your client token. That's a secret; your
+application ID isn't. It's an 18-digit number, give or take. That URL can be used
+by anyone to invite the bot to their server. It will prompt you for which server
+to invite it to and ask you if you want to grant it a bunch of server permissions.
+Give it everything it asks for. It'll probably be fine.
+
+> [!NOTE] The other big multidigit number in that URL is the permissions mask, and
+> it affects what checkboxes appear in that invite screen. That number is determined
+> using the calculator in the application dashboard at the bottom of the Bot section.
+> While I started out being more selective in only requesting the permissions I
+> knew I needed, I kept bumping into access errors for one thing or another. So
+> now I'm just like gimme damn near everything unless I know for sure I don't need it.
+
+## Configure bot for your server
+
+You can verify the bot is working by typing `$rb_hello` in chat on that server
+and it should reply to you.
+
+The bot has a number of "cogs" (a term the Discord.py library uses) for distinct
+bits of functionality with their own commands and subcommands. E.g. the thingy
+that detects join raids is its own cog. They're all disabled by default, so
+you'll want to enable whichever ones suit you.
+
+More details in [Commands][commands.md].

rocketbot/cogs/patterncog.py

@@ -204,7 +204,7 @@ class PatternCog(BaseCog, name='Pattern Matching'):
 		description='Adds a custom pattern. Patterns use a simplified ' + \
 			'expression language. Full documentation found here: ' + \
 			'https://git.rixafrix.com/ialbert/python-app-rocketbot/src/' + \
-			'branch/master/patterns.md',
+			'branch/main/docs/patterns.md',
 		usage='<pattern_name> <expression...>',
 		ignore_extra=True
 	)