Plugin Setup Checklist

Use this checklist whenever you turn on a plugin. The individual plugin pages contain the exact fields and examples; this page explains the setup steps they all share.

Before you enable anything

1. Open your server in the dashboard and confirm you have editor or admin dashboard access. A viewer can inspect settings, but cannot save them.
2. Open Setup > Access & Permissions and give your staff Discord command levels. Dashboard access and command levels are separate.
3. Put the HepBoat role above every role it must grant, remove, or use as a mute role. Discord will reject role changes above the bot's highest role.
4. Give the bot access to every channel it must read or write. A valid channel ID is not enough if Discord permissions hide the channel from the bot.
5. Set up at least one moderation log channel before enabling automatic moderation. A rule that acts without a visible audit trail is much harder to tune safely.
6. Check the dashboard page for a feature lock. A config block cannot bypass a missing feature grant.

The repeatable setup flow

1. Open the feature's dashboard page. Guided forms are the easiest route. The Config page remains available for fields that do not have a form.

2. Create the plugin block. Most plugins run only when plugins.<name>: exists. An empty block enables the defaults:

   plugins:
     utilities: {}
   

3. Configure dependencies first. Examples include a mute role for role mutes, a submissions channel for Applications, or a log channel for a honeypot.

4. Start with the smallest safe scope. Use one test channel, exempt staff, choose shadow or no-punishment modes where offered, and keep thresholds generous for the first test.

5. Save and open Diagnostics. Diagnostics catches missing grants, deleted channels, disabled dependencies, and other settings that parse correctly but cannot work in your server.

6. Run the verification on the plugin page. Test with a non-staff account or a role at the level the rule targets. Staff exemptions are a common reason a test appears to do nothing.

7. Check the result in all three places: the member-facing response, the configured mod log, and the relevant dashboard data page.

8. Expand the scope only after the small test passes. Add production channels, lower thresholds, or switch from shadow to enforce.

Every dashboard save edits the same YAML document as the Config page. It keeps comments, records history, and reloads the bot live. If a change behaves badly, restore the earlier version from Config > History.

Where each feature is configured

Feature	Main dashboard page	Dependency to settle first	First verification
Admin, welcomes, join roles	Setup > Welcome & Roles	Bot role hierarchy and destination channels	Join with a test account and confirm the welcome and roles
Infractions	Setup > Moderation	Mute role for role mutes; Discord Ban, Kick, and Moderate permissions	Warn a test member, then find the numbered record
Mod Log	Mod Log	A channel the bot can view and post in	Subscribe to Config updated, then save a harmless config change
Censor	Setup > Filters	Manage Messages; mute role if escalation mutes	Use the message simulator, then post the same test as a regular member
Spam	Setup > Filters	Manage Messages; punishment permissions	Start with punishment: NONE and confirm Spam violation logs
AutoMod	AutoMod	Discord AutoMod management permission for editing	Create a disabled keyword rule, verify it appears, then enable it
Honeypot	Setup > Honeypot	Trap channel, action permission, dedicated log channel	Post as a non-staff test account and reverse the action if needed
Image Scan	Image Scan	IMAGE_SCAN; censor rules for OCR; scan log channel	Start in shadow mode and post an image you taught
Applications	Applications	Submissions channel, questions, reviewer access	Submit a short test application and decide it from the queue
Auto Level	Levels	Role hierarchy for rewards; Rank Cards grant for image cards	Send messages as a regular member, then inspect the live XP overview
Starboard	Setup > Starboard	Board channel and source-channel visibility	Star a test message until it reaches the threshold
Custom Commands	Custom Commands	CUSTOM_COMMANDS for execution	Build a reply command, save it, and invoke it in a test channel
Tags	Tags	Plugin block and command access	Create, run, edit, and delete a disposable tag
Music	Setup > Music	MUSIC; Connect and Speak in the voice channel	Join voice, play one track, then test skip with the intended role
Games	Setup > Games	GAMES; role hierarchy for the role shop	Claim a daily reward and run one zero-risk balance check
Quests	Setup > Quests	QUESTS; GAMES for coin rewards; QUESTS_PRO for XP and role rewards	Build a one-action quest, complete it, then claim it with quests
RSS Feeds	Setup > RSS Feeds	RSS; a channel the bot can post in	Add a feed, press Test feed, then wait for the first real item
Utilities and channel rules	Setup > Channel Rules	Manage Messages for restrictions and auto-clean	Apply one rule to a test channel and post one allowed and denied message
Commands and slash opt-in	Setup > Access & Permissions; Slash Commands	Discord command scope on the bot invite	Use Would it run?, save one slash command, then invoke it

Reading IDs and durations

Turn on Discord Developer Mode under User Settings > Advanced, then right-click a user, role, channel, category, or message and choose Copy ID. Keep IDs quoted only when YAML would otherwise treat them as numbers; HepBoat normalizes Discord snowflakes to strings when it loads the config.

Durations use combinations such as 30m, 2h, 3d, 1w, or 1h30m where the field documents duration text. Some older numeric fields use seconds, so follow the example on that plugin page instead of assuming a unit.

When a configured feature does nothing

Check these in order:

1. Is the plugin block present and, if it has one, is enabled: true?
2. Does the dashboard show a missing feature grant?
3. Does Diagnostics name a deleted channel, role, or inactive dependency?
4. Is the test member exempt because of their command level or staff role?
5. Is the channel outside an allowlist, inside a blocklist, or under an excluded category?
6. Can the bot see the channel and act on the member under Discord's role hierarchy?
7. Did the event reach a mod log channel that subscribes to it?
8. For slash commands, did you opt that exact command in on the Slash Commands page, and was the bot invited with the application commands scope?

If the YAML saves successfully but the result is still unclear, include the plugin name, the relevant config block, the Diagnostics result, and a link to the failed test when asking for help. Never paste tokens, payment credentials, or private API keys.