Changing the server

Four tools, all of them behind Discord's own Administrator permission on the person asking. See The permission model for how that is decided.

Reading first

discord_guild_read returns the shape of the server: every category and channel, every role in Discord's real order, and which roles sit above her and are therefore out of her reach. It says so when she is not an administrator herself, because then the list may not be every channel and a summary that does not admit that claims a completeness it lacks.

Roles are ordered by asking the library, never by comparing position numbers. Discord lets roles share a position and breaks the tie by age; compared as integers, a fresh server reads as though everything is above her and she refuses work she could do.

One batch, one card: discord_act

Up to 20 changes in one call, applied in the order given, with 0.35 s between mutating calls so a burst does not trip Discord's rate limiter. One call is one approval card, not fifteen.

The 27 operations she can put in a batch:

create_channel · rename_channel · move_channel · set_topic · set_slowmode · delete_channel · create_category · rename_category · delete_category · create_role · rename_role · recolor_role · set_role_flags · delete_role · give_role · take_role · kick · ban · timeout · move_to_voice · nickname · post_message · set_permissions · make_private · make_public · set_forum · forum_post

Five of them are destructive and are named as such on the card: delete_channel, delete_category, delete_role, kick, ban.

Three properties are worth knowing before you approve one:

• Refusals are computed before the card. Anything the batch cannot do — a role that does not exist, a role above hers, a role managed by an integration, a person above her, the server owner, a permission name Discord does not have, a request for administrator — is said in words, and none of the batch runs. A card must never promise something impossible.
• Every operation is declarative. Creating a channel or role that is already there by that name leaves it alone and says so, instead of making a second one.
• A failure stops the run. She reports what was done, what stopped her, and how many changes did not run — never a half-applied permissions model carried on past a 403.

Inside one batch, later actions may use what earlier ones created: "create the role, then give it to her" is checked against the server plus what the batch will have made by then.

Plan, revise, apply

For anything bigger than a batch there are three steps.

discord_plan takes the shape you want and returns a numbered list of what would change. It touches nothing. Call it again with the plan id and any of drop_changes (by those numbers), protect (names that must never be touched), drop_kinds (leave roles alone, say) or allow_delete. The plan is written into her workspace, under discord/<server id>/.

Silence means keep. Deletion is off for every kind unless allow_delete turns it on for that kind. Leaving something out of the desired shape leaves it exactly as it is. Once deletion is on for a kind, anything of that kind the plan does not name is a deletion — which is why the tool is told to say that plainly when it shows you the list.

Deletions run last, so any earlier failure aborts the run before a single one has happened.

discord_apply_plan re-diffs the plan against a fresh reading of the server every time, so a plan can never act on a server that moved under it. Changes you dropped stay dropped: they are recorded on the plan rather than edited out, so a later re-diff cannot quietly bring back the one you said no to.

Before its first change it writes a snapshot of the server as it is, and the card names the file. The card also says, in as many words, that this is not an undo: recreating a channel does not bring its messages back.

If the plan deletes more than 12 things, it refuses until it is called again with confirm_deletes, so a large removal is always a second, deliberate answer.

Each applied change is journalled, so a run that stopped partway can be resumed and will skip what already happened. A plan too old to match its own journal is refused rather than guessed at.

The three limits she will not cross

• Never administrator. Nobody can meaningfully consent on a card to every permission, forever, including the ones that would let the holder undo the consent.
• Never above herself. A role at or above her top role, a role managed by an integration, a person whose top role is above hers, and the server owner are all out of reach — and she says which it was, and that moving her role higher would fix the first case.
• Never a count where a name belongs. Deletions on a card are listed by name. A number is the one thing nobody can consent to.