From a09942a0195bbc8fde4f611cab509ff5afd54fc3 Mon Sep 17 00:00:00 2001
From: Kingston-SCYD <odscheidel@gmail.com>
Date: Fri, 5 Jun 2026 16:15:29 -0500
Subject: [PATCH] Add comprehensive README with full command documentation

---
 README.md | 534 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 534 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3fda8ed
--- /dev/null
+++ b/README.md
@@ -0,0 +1,534 @@
+# Scrapyard Cogworks
+
+🔧 **A collection of custom Red-DiscordBot cogs by Scrapyard Cogworks**
+
+🌐 Homepage: https://homepage.kingstons-scrapyard.net/
+
+---
+
+## Installation
+
+```
+[p]repo add scrapyard http://192.168.0.200:3000/kingston/scrapyard-cogworks.git
+[p]cog install scrapyard autoroom
+[p]load autoroom
+```
+
+---
+
+## AutoRoom
+
+Automatic voice channel management. When a member joins an AutoRoom Source (voice channel), a brand new AutoRoom is created that they have control over. Once everyone leaves the AutoRoom, it is automatically deleted.
+
+### Requirements
+
+- Python 3.11+
+- Red-DiscordBot 3.5.0+
+- Dependencies: `func-timeout`, `jinja2`
+
+---
+
+## User Commands
+
+All user commands are under the `[p]autoroom` group (alias: `[p]vc`).
+
+---
+
+### `[p]autoroom settings`
+
+**Aliases:** `about`, `info`
+
+Display current settings for the AutoRoom you are currently in. Shows:
+
+- **Owner** - The current owner of the AutoRoom (or "Server Managed" if no owner)
+- **Access** - Whether the room is public, locked, or private
+- **Member Roles** - Roles that are allowed to access the room (if applicable)
+- **Bitrate** - Current bitrate in kbps
+- **Channel Age** - How long the AutoRoom has existed
+- **Allowed Members** - Members explicitly allowed into the room
+- **Allowed Roles** - Roles explicitly allowed into the room
+- **Denied Members** - Members explicitly denied from the room
+- **Denied Roles** - Roles explicitly denied from the room
+
+You do not need to be the owner of the AutoRoom to use this command.
+
+---
+
+### `[p]autoroom name <name>`
+
+Change the name of your AutoRoom.
+
+- Maximum channel name length: 100 characters (truncated if longer)
+- Rate limited to prevent abuse. If you hit the rate limit, you will be told how long to wait.
+- Alternatively, you can rename the channel directly through Discord (right-click on desktop, long-press on mobile). Note: if the server has 2FA enabled, your account needs 2FA to do this.
+
+**Example:**
+```
+[p]autoroom name Chill Zone
+```
+
+---
+
+### `[p]autoroom bitrate <kbps>`
+
+**Aliases:** `kbps`
+
+Change the bitrate of your AutoRoom.
+
+- Minimum: 8 kbps
+- Maximum: Server's bitrate limit (depends on server boost level)
+
+**Example:**
+```
+[p]autoroom bitrate 96
+```
+
+---
+
+### `[p]autoroom users <limit>`
+
+**Aliases:** `userlimit`
+
+Change the user limit of your AutoRoom.
+
+- Minimum: 0 (unlimited)
+- Maximum: 99
+
+**Example:**
+```
+[p]autoroom users 5
+```
+
+---
+
+### `[p]autoroom claim`
+
+Claim ownership of an AutoRoom.
+
+- You must be in the AutoRoom to claim it.
+- You can only claim an AutoRoom if the current owner has left the channel.
+- There is a cooldown after the owner leaves before you can claim, in case they come back.
+- Moderators, admins, and the server owner can claim at any time regardless of the above restrictions.
+- When you claim, the previous owner loses their owner permissions and you gain them.
+
+---
+
+### `[p]autoroom public`
+
+Make your AutoRoom public.
+
+- The room becomes visible and joinable by everyone (or by all member roles if configured).
+- All member roles (or @everyone) will be granted connect permissions.
+
+---
+
+### `[p]autoroom locked`
+
+Lock your AutoRoom.
+
+- The room remains visible to everyone but no one can join without being explicitly allowed.
+- Users already in the room will remain.
+- Use `[p]autoroom allow` to let specific users in.
+
+---
+
+### `[p]autoroom private`
+
+Make your AutoRoom private.
+
+- The room becomes invisible and unjoinable by other users.
+- Users already in the room will remain.
+- Use `[p]autoroom allow` to let specific users in.
+
+---
+
+### `[p]autoroom allow <members_or_roles...>`
+
+**Aliases:** `add`
+
+Allow one or more users (or roles) into your AutoRoom.
+
+**⚡ Scrapyard Cogworks Enhancement:** You can specify multiple users/roles separated by spaces to allow them all at once.
+
+**Accepts:**
+- @mentions
+- User IDs
+- Usernames
+- Role mentions
+- Role names
+
+**Restrictions:**
+- The user/role must be allowed to connect to the original AutoRoom Source channel. If they can't connect to the source, they can't be allowed into the AutoRoom.
+- If the AutoRoom uses member roles, you cannot allow a role that is lower in hierarchy than the lowest member role.
+- Bot roles can always be allowed.
+
+**Examples:**
+```
+[p]autoroom allow @User1
+[p]autoroom allow @User1 @User2 @User3
+[p]autoroom allow 123456789012345678 987654321098765432
+[p]autoroom allow @User1 123456789012345678 @SomeRole
+```
+
+---
+
+### `[p]autoroom deny <member_or_role>`
+
+**Aliases:** `ban`, `block`
+
+Deny a user (or role) from accessing your AutoRoom.
+
+- If the user is currently in your AutoRoom, they will be disconnected.
+- If a role is denied and any members in the room no longer have connect permission as a result, they will be disconnected.
+- If the server uses member roles, denying roles may not work as expected.
+
+**Cannot deny:**
+- The bot itself
+- Yourself (the AutoRoom owner)
+- The server owner
+- Server admins or admin roles
+- Server moderators or moderator roles
+
+**Example:**
+```
+[p]autoroom deny @TroubleMaker
+[p]autoroom deny 123456789012345678
+```
+
+---
+
+## Admin Commands
+
+All admin commands are under the `[p]autoroomset` group. Requires the **Manage Server** permission or an admin role.
+
+---
+
+### `[p]autoroomset settings`
+
+Display all current AutoRoom settings for the server, including:
+
+- Admin access to all AutoRooms (on/off)
+- Moderator access to all AutoRooms (on/off)
+- Bot roles allowed in all AutoRooms
+- Per-source settings: room type, destination category, legacy text channel, send messages permission, owner manage channel permission, member roles, room name format, text channel hint, and text channel topic
+
+Also displays warnings if the bot is missing required or optional permissions.
+
+---
+
+### `[p]autoroomset permissions`
+
+**Aliases:** `perms`
+
+Check that the bot has all needed permissions for all configured AutoRoom Sources.
+
+Displays a detailed breakdown per AutoRoom Source showing:
+- Required permissions (the cog won't function without these)
+- Optional permissions (extra features that won't work without these)
+- Where permissions need to be granted (source channel, destination category, or server-wide)
+
+---
+
+### `[p]autoroomset create <source_voice_channel> <dest_category>`
+
+**Aliases:** `enable`, `add`
+
+Create a new AutoRoom Source through an interactive setup wizard.
+
+**Parameters:**
+- `source_voice_channel` - The voice channel that users will join to trigger AutoRoom creation
+- `dest_category` - The category where new AutoRooms will be created
+
+**The wizard will ask you to configure:**
+
+1. **Room Type:**
+   - `public` - Visible and joinable by all. Owner can kick/ban users.
+   - `locked` - Visible but not joinable. Owner must allow users in.
+   - `private` - Hidden and not joinable. Owner must allow users in.
+   - `server` - Public but with no owner. Cannot be modified by users.
+
+2. **Channel Name Format:**
+   - `username` - Shows as "Username's Room"
+   - `game` - Shows the owner's current game, falls back to username format
+
+**Example:**
+```
+[p]autoroomset create #create-a-room "Auto Rooms"
+```
+
+---
+
+### `[p]autoroomset remove <autoroom_source>`
+
+**Aliases:** `disable`, `delete`, `del`
+
+Remove an AutoRoom Source. The voice channel will remain but will no longer trigger AutoRoom creation.
+
+**Example:**
+```
+[p]autoroomset remove #create-a-room
+```
+
+---
+
+### `[p]autoroomset access`
+
+Control access to all AutoRooms for admin/moderator roles.
+
+---
+
+### `[p]autoroomset access admin`
+
+Toggle whether admins can join locked/private AutoRooms. This is a toggle - run again to disable.
+
+---
+
+### `[p]autoroomset access mod`
+
+Toggle whether moderators can join locked/private AutoRooms. This is a toggle - run again to disable.
+
+---
+
+### `[p]autoroomset access bot add <role>`
+
+Allow a bot role to automatically be granted access to every AutoRoom. The AutoRoom Owner can still manually deny these roles if they choose.
+
+**Example:**
+```
+[p]autoroomset access bot add @MusicBot
+```
+
+---
+
+### `[p]autoroomset access bot remove <role>`
+
+**Aliases:** `delete`, `del`
+
+Remove a bot role from being automatically allowed into every AutoRoom.
+
+**Example:**
+```
+[p]autoroomset access bot remove @MusicBot
+```
+
+---
+
+### `[p]autoroomset modify`
+
+**Aliases:** `edit`
+
+Group command for modifying an existing AutoRoom Source's settings.
+
+---
+
+### `[p]autoroomset modify category <autoroom_source> <dest_category>`
+
+Change the destination category where AutoRooms will be created for a given source.
+
+**Example:**
+```
+[p]autoroomset modify category #create-a-room "New Category"
+```
+
+---
+
+### `[p]autoroomset modify type public <autoroom_source>`
+
+Set the AutoRoom Source to create public rooms (visible and joinable, owner has control).
+
+---
+
+### `[p]autoroomset modify type locked <autoroom_source>`
+
+Set the AutoRoom Source to create locked rooms (visible but not joinable, owner must allow users).
+
+---
+
+### `[p]autoroomset modify type private <autoroom_source>`
+
+Set the AutoRoom Source to create private rooms (hidden, owner must allow users).
+
+---
+
+### `[p]autoroomset modify type server <autoroom_source>`
+
+Set the AutoRoom Source to create server-managed rooms (public, no owner, cannot be modified).
+
+---
+
+### `[p]autoroomset modify name username <autoroom_source>`
+
+Set the channel name format to the username style.
+
+**Format:** `{{username}}'s Room{% if dupenum > 1 %} ({{dupenum}}){% endif %}`
+
+**Example output:** `Kingston's Room`, `Kingston's Room (2)`
+
+---
+
+### `[p]autoroomset modify name game <autoroom_source>`
+
+Set the channel name format to the game style. Shows the owner's currently playing game, or falls back to the username format.
+
+**Format:** `{{game}}{% if not game %}{{username}}'s Room{% endif %}{% if dupenum > 1 %} ({{dupenum}}){% endif %}`
+
+**Example output:** `Minecraft`, `Kingston's Room`
+
+---
+
+### `[p]autoroomset modify name custom <autoroom_source> <template>`
+
+Set a custom channel name format using Jinja2-like template syntax.
+
+**Available variables:**
+| Variable | Description |
+|----------|-------------|
+| `username` | AutoRoom Owner's display name |
+| `game` | AutoRoom Owner's current game (empty string if not playing) |
+| `dupenum` | Incrementing number starting at 1, for de-duplicating names |
+
+**Statements supported:**
+- `{% if %}` / `{% elif %}` / `{% else %}` / `{% endif %}`
+
+**Examples:**
+```
+[p]autoroomset modify name custom #create-a-room {{username}}'s Chill Zone
+[p]autoroomset modify name custom #create-a-room {% if game %}Playing {{game}}{% else %}{{username}}'s Room{% endif %}
+```
+
+---
+
+### `[p]autoroomset modify text set <autoroom_source> <hint_text>`
+
+Set a message that will be sent in the AutoRoom's built-in text channel when it is created.
+
+Supports the same template variables as channel names, plus:
+| Variable | Description |
+|----------|-------------|
+| `mention` | The AutoRoom Owner's @mention (pings them) |
+
+**Example:**
+```
+[p]autoroomset modify text set #create-a-room Hello {{mention}}! Welcome to your AutoRoom. Use `[p]autoroom` to manage it.
+```
+
+---
+
+### `[p]autoroomset modify text disable <autoroom_source>`
+
+Disable sending a message to newly created AutoRoom text channels.
+
+---
+
+### `[p]autoroomset modify specialperms ownermodify <autoroom_source>`
+
+Toggle whether AutoRoom Owners get the **Manage Channels** permission on their AutoRoom. This allows them to modify the channel using native Discord controls (name, bitrate, user limit, etc.).
+
+This is a toggle - run again to disable.
+
+---
+
+### `[p]autoroomset modify specialperms sendmessage <autoroom_source>`
+
+Toggle whether users can send messages in the AutoRoom's built-in text channel.
+
+This is a toggle - run again to disable.
+
+---
+
+### `[p]autoroomset modify legacytextchannel enable <autoroom_source>`
+
+Enable the creation of a separate legacy text channel alongside the AutoRoom voice channel. This text channel will be visible only to members in the voice channel and will be deleted when the AutoRoom is deleted.
+
+---
+
+### `[p]autoroomset modify legacytextchannel disable <autoroom_source>`
+
+Disable the creation of a legacy text channel with new AutoRooms.
+
+---
+
+### `[p]autoroomset modify legacytextchannel topic set <autoroom_source> <topic_text>`
+
+Set the topic for the legacy text channel. Supports template variables.
+
+**Example:**
+```
+[p]autoroomset modify legacytextchannel topic set #create-a-room This channel is for {{username}}'s room. It will be deleted when everyone leaves.
+```
+
+---
+
+### `[p]autoroomset modify legacytextchannel topic disable <autoroom_source>`
+
+Disable setting a topic on the legacy text channel.
+
+---
+
+### `[p]autoroomset modify defaults`
+
+**Aliases:** `bitrate`, `memberrole`, `other`, `perms`, `users`
+
+Displays information about how AutoRoom defaults are configured:
+
+- **Bitrate/User Limit** - Copied from the AutoRoom Source channel to the created AutoRoom.
+- **Member Roles** - To restrict who can use AutoRooms, deny @everyone from viewing/connecting to the AutoRoom Source and allow only specific roles.
+- **Permissions** - All permission overwrites (except Manage Roles) are copied from the AutoRoom Source to the AutoRoom. The bot must have each permission allowed in the destination category or server-wide for it to be copied.
+
+---
+
+## How It Works
+
+1. An admin creates an **AutoRoom Source** - a voice channel that acts as a trigger.
+2. When a user joins the AutoRoom Source, the bot:
+   - Creates a new voice channel (AutoRoom) in the configured destination category
+   - Moves the user into the new channel
+   - Grants the user ownership permissions over the channel
+3. The AutoRoom Owner can then:
+   - Rename the channel
+   - Change bitrate and user limits
+   - Make it public, locked, or private
+   - Allow or deny specific users and roles
+4. When all users leave the AutoRoom, it is automatically deleted.
+
+---
+
+## Permissions Required
+
+The bot needs the following permissions:
+
+**Required (server-wide or on source + destination category):**
+- Manage Channels
+- Manage Roles
+- Move Members
+- Connect
+- View Channel
+
+**Optional (for full feature support):**
+- Any permission overwrite on the AutoRoom Source that you want copied to AutoRooms must be allowed for the bot in the destination category.
+
+---
+
+## Scrapyard Cogworks Modifications
+
+This fork includes the following enhancements over the original PhasecoreX version:
+
+### Multi-Allow Support
+The `[p]autoroom allow` command now accepts multiple users/roles in a single command. Instead of running the command multiple times, you can whitelist everyone at once:
+
+```
+[p]autoroom allow @User1 @User2 @User3 123456789012345678
+```
+
+---
+
+## Credits
+
+- Originally developed by [PhasecoreX](https://github.com/PhasecoreX/PCXCogs)
+- Modified and maintained by Scrapyard Cogworks
+
+---
+
+## Support
+
+Visit us at https://homepage.kingstons-scrapyard.net/