docs: permission grants

Dashboard.md: what a grant and a deny are, how they combine with GM levels, what can't be granted, who may manage
them (grants_manage, nothing you don't hold, the rank rules), where they are managed, live changes, audit log entries
and the API. Commands.md: how grants and denies apply to slash commands.

Check: the new sections read correctly and the link from Commands.md to Dashboard.md#permission-grants works.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/Commands.md

@@ -221,3 +221,20 @@ There are 9 Game master levels
 |7|INACTIVE_DEVELOPER|Inactive developer, limited permissions.|
 |8|DEVELOPER|Active developer, full permissions on live.|
 |9|OPERATOR|Can shutdown server for restarts & updates.|
+
+## Grants
+
+A command's GM level can be bypassed for one account or character with a grant on the dashboard (Permissions page,
+Grants tab, or the account or character page; see [Dashboard.md](Dashboard.md#permission-grants)). A command may be
+used when:
+
+- the character's GM level reaches the command's level, or a grant covers it: the command itself, every command up to a
+  GM level, or the dashboard permission the command follows (`accounts_kick` covers `/kick`), and
+- no deny covers it. Denies never apply to GM 9 accounts, also while they play at a lower level.
+
+Account grants count for every character of the account; character grants for that character only. Expired and removed
+grants count for nothing. Grants never take anyone below a command's floor above GM 1 (`/execute`: GM 8), and commands
+the client handles keep their fixed level. Commands that act on another player still follow the rank rules with the
+character's GM level (grants of `self_*` and `manage_equal_rank` count). A command a deny takes away answers "it was
+taken away from you". `/help` lists the commands a player may use, grants included. Changes reach online players at
+once.

docs/Dashboard.md

@@ -62,7 +62,7 @@ What people can do depends on their account's GM level. Out of the box:
 | 4+ | Ban and lock accounts; email password reset links |
 | 5+ | Moderate pet names, properties and leaderboards; revoke strikes; change a character's missions; change the chat filter's words; send and schedule announcements |
 | 8+ | Manage accounts (create, change email or password, reset two-factor login) and GM levels; edit characters and replace their XML; give items back; read whispers and team chat; send chat into the game; attach items to mail, to one player or everyone; import models; shut down worlds; schedule restarts and events; run economy checks; play keys, client files and the vanity files; see scheduled tasks, the audit log, server logs, crash dumps, server health and instance load; the developer tools |
-| 9 | Delete accounts; change scheduled tasks, instance limits, settings and permissions (these two are always GM 9 only), webhooks and email settings; backups |
+| 9 | Delete accounts; grant permissions to single accounts and characters; change scheduled tasks, instance limits, settings and permissions (these two are always GM 9 only), webhooks and email settings; backups |
 
 Each of these is a named permission, and you can change the lowest GM level allowed for any of them without rebuilding
 or restarting:
@@ -88,6 +88,9 @@ mailing them to your own characters also needs `self_items` (below), and without
 
 Set `min_dashboard_gm_level` to keep lower levels out of the dashboard entirely.
 
+Single accounts and characters can also be given or denied a permission or command with a grant (see
+[Permission grants](#permission-grants)).
+
 ### Acting on yourself and on your own rank
 
 GM 9 can use every tool on anyone, including their own account and other GM 9 accounts. Two safety rails remain: the
@@ -190,6 +193,47 @@ permission:
 
 A refused command says why in the chat and names the permission. The page shows each command's rule on its card.
 
+### Permission grants
+
+A grant gives one account or character a permission or command on top of what its GM level allows; a deny takes one
+away. What someone may do:
+
+    allowed = (GM level allows it OR a grant covers it) AND no deny covers it
+
+A grant or deny names one of:
+
+- a dashboard permission (`permission`); it also covers the in-game commands that follow it
+- an in-game command (`command`)
+- every permission of a category (`permission_group`), for example Accounts
+- every command up to a GM level (`command_group`), 1 to 9
+
+Each has an optional expiry, a note, and who gave it and when. Rules:
+
+- A deny beats a grant. Denies never apply to GM 9 accounts.
+- `settings` and `permissions_manage` stay GM 9 only: they can't be granted and no group covers them. Commands with a
+  fixed level and commands with a floor above GM 1 (`/execute`) can't be granted.
+- On the dashboard only the account's grants count. In game the account's and the logged-in character's count.
+- `min_dashboard_gm_level` still keeps lower levels out of the dashboard entirely.
+- Grants count wherever permissions are checked: pages and API routes, the rank rules (`self_*`, `manage_equal_rank`),
+  API access and API key scopes (a key never does more than its owner may now), and live updates over the WebSocket.
+
+**Managing them** needs `grants_manage` (default GM 9). Nobody grants or denies what they don't hold themselves (every
+permission of a group; a command they may use; command groups only up to their own GM level), and only on accounts the
+rank rules let them manage (their own with `self_moderation`). Removing a grant follows the same rules. Where:
+
+- The **Grants** tab of the Permissions page: every grant in force, the history, and a form that searches accounts or
+  characters by name. With only `grants_manage` the page shows just this tab.
+- The **Permission grants** card on account and character pages. Players see their own grants there, read-only.
+
+The form offers only what you may grant. Changes apply at once: the dashboard reads the account's grants with every
+request, and online players get them through master (`REFRESH_ACCOUNT` / `REFRESH_CHARACTER`) without relogging. Every
+change goes in the audit log (`grant_permission`, `deny_permission`, `remove_grant`). Removed grants are kept, so the
+list is also the history.
+
+API: `GET /api/grants/catalog`, `GET /api/grants` (`?account=ID` or `?character=ID`), `POST /api/grants`
+(`{targetType, target, kind, name, deny, expiresAt, note}`), `POST /api/grants/:id/remove`. Stored in the
+`permission_grants` table.
+
 ## Settings
 
 The **Settings** page (GM 9) lists every setting the servers read, grouped by what it's for (Server, Gameplay,