velox-bot/docs/beta-features.md

Beta features

A beta feature is one that only a few chosen people can use while it is still being tried out. The same rule applies on the bot and on the dashboard: you can use beta features if you are a member of the beta server and hold the Beta Tester role.

Who the testers are

• The beta server and the Beta Tester role are chosen by the bot's owner on the dashboard, under Admin, Beta access. Only the owner can see or change this page.
• Giving someone the role in Discord makes them a tester. Taking it away removes their access: within about 30 seconds on the bot, and within about 30 seconds on the dashboard API.
• Until a role is chosen, nobody has beta access.
• The settings are stored in the beta_settings table (one row). The API writes it, and the bot polls it every 30 seconds. There is nothing to put in .env.

Access fails closed. If the settings cannot be read, if the role or the server is not set, if a person is not in the server, if a command is used in a DM, or if Discord cannot be reached, access is denied.

On the bot

Code: internal/beta (the gate), internal/commands/commands.go (RegisterBeta), internal/bot/bot.go (WatchBeta, registerBetaCommands), internal/commands/betacmd (/beta).

• Beta commands are registered only in the beta server, so nobody else sees them in the command menu.
• Each beta handler is wrapped in beta.Gate, which checks that the interaction came from the beta server and that the member has the role. If not, the user gets "This feature is in beta and isn't available to you yet." (Autocomplete requests get an empty list.) Hiding the command is never the only protection.
• If the owner changes the beta server on the dashboard, the bot moves the beta commands to the new server within 30 seconds and removes them from the old one. Commands in the beta server that are neither regular nor beta commands are removed too. If the beta server is also GUILD_ID, the regular commands are kept.
• /beta shows the owner how access is set up. Only the owner of the Discord application can run it, and it is hidden from everyone but administrators.

Add a beta command

Write the command like any other (see the Development guide), but instead of adding it to AllCommands and handlers, register it from commands.go:

func init() {
	RegisterBeta(mything.MyThing, mything.MyThingHandler)
}

RegisterBeta adds the definition to BetaCommands and the handler, wrapped in beta.Gate, to the dispatcher. Buttons and forms that belong to a beta command need the same care: check beta.Guard(s, i) at the top of their handlers, because a custom ID can be reached from an old message.

Release it

Move the definition into AllCommands and the handler into the handlers map, and delete the RegisterBeta call. On the next start the command appears everywhere, and it is removed from the beta server's own list because it is now a regular command.

On the API and dashboard

These live in the other two repositories.

• API: put the feature's routes under /api/v1/beta. That route group sits behind a betaOnly middleware, which asks Discord whether the signed-in user holds the role in the beta server (with a 30-second memory) and answers 403 otherwise. GET /users/me also returns is_beta, which the dashboard uses to decide what to show.
• Dashboard: give a route meta: { requiresBeta: true } to keep its page away from non-testers, and use is_beta to hide its links. This is only about display. The API checks access on every request, so a page that was shown by mistake still cannot read or change anything.

Why it works this way

• The role in Discord is the single list of testers, so there is no second list to keep in step with it.
• Access is decided by the server (bot and API), never by the browser.
• Beta commands do not exist outside the beta server, and the gate checks again when they run.
• The settings are in the database, not in the environment, so the owner can change them without a deploy.