docs(plugins): clarify permission requirements for non-built-in plugins

docs/src/plugin-aliases.md

@@ -23,6 +23,8 @@ Aliases can be added to this block or changed to swap the default built-in plugi
 
 When swapping the default aliases for custom plugins, it's important that these plugins implement the basic contract Zellij (and indeed, other plugins) expect of them. The following sections describe the contract for each default alias.
 
+> **Important:** Built-in plugins (`zellij:` prefix) are automatically granted all [permissions](./plugin-api-permissions.md). When you swap a built-in alias to a `file:` plugin, the replacement **must** call `request_permission()` in its `load()` function with the permissions it needs — otherwise privileged API calls will be silently denied, causing the plugin to crash. See [Permissions](./plugin-api-permissions.md) for details.
+
 Here's an example on how to use the plugin alias in a layout:
 
 ```javascript

docs/src/plugin-api-permissions.md

@@ -4,6 +4,26 @@ The plugin system provides a permission system to provide extra security and pro
 The system places certain [Events](./plugin-api-events.md) and [Commands](./plugin-api-commands.md) behind certain permissions.
 Plugins who want to listen to these events or use these commands should prompt the user to grant them these permissions with the `request_permission` command.
 
+## How permissions work
+
+**Built-in plugins** (loaded via the `zellij:` URL scheme) are automatically granted all permissions and do not need to call `request_permission`.
+
+**All other plugins** (loaded via `file:`, `http(s):`, or bare aliases pointing to non-`zellij:` URLs) **must** call `request_permission` in their `load()` function before using any privileged API call. If a plugin uses a command or subscribes to an event that requires a permission it has not been granted, the command will be **silently denied** — no response will be sent back to the plugin, which will likely cause a panic.
+
+```rust
+fn load(&mut self, configuration: BTreeMap<String, String>) {
+    request_permission(&[
+        PermissionType::ReadApplicationState,
+        PermissionType::ChangeApplicationState,
+    ]);
+    // ...
+}
+```
+
+On first load, Zellij will display a permission dialog to the user. Once granted, permissions are cached and will not be requested again.
+
+> **Important:** If you are forking a built-in plugin (e.g. `session-manager`) and loading it via `file:`, you must add `request_permission()` to its `load()` function — built-in plugins do not include this call since they bypass permission checks entirely.
+
 ## Permissions
 ### ReadApplicationState
 Access Zellij state (Panes, Tabs and UI)

docs/src/plugin-lifecycle.md

@@ -16,7 +16,9 @@ pub trait ZellijPlugin {
 
 ## Lifecycle Methods
 ### load
-Will be called when the plugin is loaded, this is a good place to [subscribe](./plugin-api-commands.md#subscribe) to events that are interesting for this plugin.
+Will be called when the plugin is loaded, this is a good place to [request permissions](./plugin-api-permissions.md) and [subscribe](./plugin-api-commands.md#subscribe) to events that are interesting for this plugin.
+
+> **Note:** Non-built-in plugins (loaded via `file:` or `http(s):`) must call `request_permission()` in `load()` before using any privileged commands. See [Permissions](./plugin-api-permissions.md) for details.
 
 ### update
 Will be called with an [`Event`](./plugin-api-events.md) if the plugin is subscribed to said event. If the plugin returns `true` from this function, Zellij will know it should be rendered and call its `render` function.