Document magic permission model namespaces

Closes flarum/framework#2202

docs/extend/permissions.md

@@ -45,6 +45,30 @@ Permissions are just part of the puzzle: if you're enforcing whether a user can
 
 :::
 
-### Adding Custom Permissions
+## Permission Naming Conventions
+
+Nothing is enforced, but we generally recommend the following convention for permission naming:
+
+`extension-namespace.model-prefix.ability-name`.
+
+The extension namespace ensures that your permission won't collide with other extensions.
+
+The model prefix is useful in case you have different models but similar permissions (`flarum-sponsors.discussion.sponsor` vs `flarum-sponsors.post.sponsor`).
+
+### "Magic" model namespaces
+
+You may have seen some calls to `$actor->can` that don't use the full name of a permission; for example, `$actor->can('reply', $discussion)`, where the backing permission is actually called `discussion.reply`.
+
+This is done in core to make authorization calls shorter and simpler. Essentially, if the second argument is a discussion, Core's [DiscussionPolicy](https://github.com/flarum/core/blob/bba6485effc088e38e9ae0bc8f25528ecbee3a7b/src/Discussion/Access/DiscussionPolicy.php#L39-L44) will check the `discussion.PROVIDED_ABILITY` permission automatically.
+
+This can be used by extensions when a model namespace isn't present: for example, `$actor->can('someAbility, $discussion)` will check the `discussion.someAbility` permission if the $discussion argument is an instance of the `Discussion` model. However, this means you can't prefix your permissions with extension namespaces (or you have to put the extension namespace at the end).
+
+These magic model-based conversions are applied to discussion, group, and user authorization checks. For posts, the logic is slightly different: `$actor->can('ability', $post)` will check `$actor->('abilityPosts, $post->discusssion)` on the post's discussion.
+
+If you want to use authorization checks with an ability name that differs from the backing permission name, and these cases do not apply to your permission's naming, you'll have to use a custom policy.
+
+See our [authorization documentation](authorization.md) for more information on the `can` method, policies, and how authorization checks are processed.
+
+## Adding Custom Permissions
 
 To learn more about adding permissions through the admin dashboard, see the [relevant documentation](admin.md).