diff --git a/agent-os/security/overview.mdx b/agent-os/security/overview.mdx
index 569e0531..c1b1ef59 100644
--- a/agent-os/security/overview.mdx
+++ b/agent-os/security/overview.mdx
@@ -38,19 +38,9 @@ Set the `JWT_VERIFICATION_KEY` environment variable to your public key in your `
 export JWT_VERIFICATION_KEY="your-public-key"
 ```
 
-You can generate a key pair from the control plane when connecting a new OS or from the Settings page for an existing OS.
-
-<video
-  autoPlay
-  muted
-  controls
-  className="w-full aspect-video"
-  src="/videos/auth-on-connect-web.mp4"
-></video>
-
 Requests without a valid JWT return `401 Unauthorized`. Requests with insufficient scopes return `403 Forbidden`.
 
-See [RBAC Documentation](/agent-os/security/rbac) for scope format, available scopes, and endpoint mappings.
+See the [RBAC documentation](/agent-os/security/rbac) for the full setup flow, scope reference, and endpoint mappings.
 
 <CardGroup cols={2}>
   <Card
diff --git a/agent-os/security/rbac.mdx b/agent-os/security/rbac.mdx
index bc8d3364..d830abe0 100644
--- a/agent-os/security/rbac.mdx
+++ b/agent-os/security/rbac.mdx
@@ -44,10 +44,45 @@ agent_os = AgentOS(
 app = agent_os.get_app()
 ```
 
-Set the `JWT_VERIFICATION_KEY` environment variable to your public key in your `.env` file or export it directly in your terminal:
-```bash
-export JWT_VERIFICATION_KEY="your-public-key"
-```
+
+
+## Generate a Verification Key
+
+`authorization=True` only tells AgentOS to enforce JWT auth. To verify tokens, AgentOS also needs a public key. Generate one from the control plane and wire it in.
+
+<Steps>
+  <Step title="Toggle JWT authorization">
+    Enable JWT authorization when connecting a new AgentOS, or later from the OS Settings page.
+
+    {/* TODO: screenshot of the toggle */}
+  </Step>
+
+  <Step title="Copy the public key">
+    A modal appears with the public key for your AgentOS.
+  </Step>
+
+  <Step title="Set the verification key">
+    Set the `JWT_VERIFICATION_KEY` environment variable to your public key in your `.env` file or export it directly in your terminal:
+    ```bash
+    export JWT_VERIFICATION_KEY="your-public-key"
+    ```
+
+    Or, if you manage keys via a JWKS file, point AgentOS at it instead:
+    ```bash
+    export JWT_JWKS_FILE="/path/to/jwks.json"
+    ```
+  </Step>
+</Steps>
+
+Authorization is now active for your AgentOS.
+
+<video
+  autoPlay
+  muted
+  controls
+  className="w-full aspect-video"
+  src="/videos/auth-on-connect-web.mp4"
+></video>
 
 ## Scope Format
 
@@ -60,19 +95,53 @@ RBAC uses a hierarchical scope format:
 | `resource:*:action` | `agents:*:read` | Wildcard (equivalent to global) |
 | `agent_os:admin` | - | Full access to all endpoints |
 
+
 ## Complete Scope Reference
 
+### Organization Scopes
+
+Organization scopes are enforced at the control plane and do not map to AgentOS endpoints.
+
+| Scope | Description |
+|-------|-------------|
+| `os:read` | View AgentOS instances in the organization |
+| `os:write` | Create and update AgentOS instances |
+| `os:delete` | Delete AgentOS instances |
+| `org:read` | View organization details and members |
+| `org:write` | Update organization settings and manage members |
+| `org:delete` | Delete the organization |
+| `billing:read` | View billing details and invoices |
+| `billing:write` | Update billing settings and payment methods |
+
 ### Admin Scopes
 
 | Scope | Description |
 |-------|-------------|
-| `agent_os:admin` | Full admin access to all endpoints |
+| `agent_os:admin` | Full admin access to all AgentOS endpoints |
+
+
+
+### AgentOS config Scopes
+
+| Scope | Description |
+|-------|-------------|
+| `config:read` | View system configuration and available models |
+| `config:write` | Administrative writes such as database migrations |
 
-### System Scopes
+
+### Registry Scopes
 
 | Scope | Description |
 |-------|-------------|
-| `system:read` | View system configuration and available models |
+| `registry:read` | View the code-defined registry (tools, models, databases) |
+
+### Component Scopes
+
+| Scope | Description |
+|-------|-------------|
+| `components:read` | List and view components and their configs |
+| `components:write` | Create and update components and configs |
+| `components:delete` | Delete components and configs |
 
 ### Agent Scopes
 
@@ -176,8 +245,16 @@ AgentOS automatically maps endpoints to required scopes.
   <Tab title="System">
     | Endpoint | Required Scope |
     |----------|----------------|
-    | `GET /config` | `system:read` |
-    | `GET /models` | `system:read` |
+    | `GET /config` | `config:read` |
+    | `GET /models` | `config:read` |
+    | `POST /databases/all/migrate` | `config:write` |
+    | `POST /databases/*/migrate` | `config:write` |
+  </Tab>
+
+  <Tab title="Registry">
+    | Endpoint | Required Scope |
+    |----------|----------------|
+    | `GET /registry` | `registry:read` |
   </Tab>
 
   <Tab title="Agents">
@@ -251,8 +328,11 @@ AgentOS automatically maps endpoints to required scopes.
     | `GET /knowledge/content` | `knowledge:read` |
     | `GET /knowledge/content/*` | `knowledge:read` |
     | `GET /knowledge/config` | `knowledge:read` |
+    | `GET /knowledge/*/sources` | `knowledge:read` |
+    | `GET /knowledge/*/sources/*/files` | `knowledge:read` |
     | `POST /knowledge/search` | `knowledge:read` |
     | `POST /knowledge/content` | `knowledge:write` |
+    | `POST /knowledge/remote-content` | `knowledge:write` |
     | `PATCH /knowledge/content/*` | `knowledge:write` |
     | `DELETE /knowledge/content` | `knowledge:delete` |
     | `DELETE /knowledge/content/*` | `knowledge:delete` |
@@ -281,6 +361,7 @@ AgentOS automatically maps endpoints to required scopes.
     | `GET /traces` | `traces:read` |
     | `GET /traces/*` | `traces:read` |
     | `GET /trace_session_stats` | `traces:read` |
+    | `POST /traces/search` | `traces:read` |
   </Tab>
 
   <Tab title="Schedules">
@@ -308,8 +389,35 @@ AgentOS automatically maps endpoints to required scopes.
     | `POST /approvals/*/resolve` | `approvals:write` |
     | `DELETE /approvals/*` | `approvals:delete` |
   </Tab>
+
+  <Tab title="Components">
+    | Endpoint | Required Scope |
+    |----------|----------------|
+    | `GET /components` | `components:read` |
+    | `GET /components/*` | `components:read` |
+    | `GET /components/*/configs` | `components:read` |
+    | `GET /components/*/configs/*` | `components:read` |
+    | `GET /components/*/configs/current` | `components:read` |
+    | `POST /components` | `components:write` |
+    | `POST /components/*/configs` | `components:write` |
+    | `POST /components/*/configs/*/set-current` | `components:write` |
+    | `PATCH /components/*` | `components:write` |
+    | `PATCH /components/*/configs/*` | `components:write` |
+    | `DELETE /components/*` | `components:delete` |
+    | `DELETE /components/*/configs/*` | `components:delete` |
+  </Tab>
 </Tabs>
 
+## Access Prerequisites
+
+A few scopes gate access to everything downstream. Without them, finer-grained scopes have no effect because the user cannot reach the resources they apply to.
+
+| Scope | Without it, the user cannot |
+|-------|-----------------------------|
+| `org:read` | Access the organization at all |
+| `os:read` | List AgentOS instances in the organization |
+| `config:read` | Use any AgentOS endpoint (the UI loads `/config` on startup) |
+
 ## Custom Scope Mappings
 
 Customize or extend the default scope mappings using the JWT middleware:
@@ -339,6 +447,36 @@ app.add_middleware(
 
 Custom scope mappings are additive to the defaults. To override a default, specify the same route pattern with your custom scopes.
 
+## Custom Roles and Scopes
+
+<Note>
+Custom roles and scopes are available on the Enterprise plan. [Book a call](https://cal.com/team/agno/intro) or email [support@agno.com](mailto:support@agno.com) to enable.
+</Note>
+
+<Warning>
+Custom roles require JWT authentication. Without it, scope enforcement is skipped entirely by AgentOS and assigned roles have no effect.
+</Warning>
+
+Compose scopes into named roles in the control plane and assign them to users in your organization. Members inherit the scopes of every role assigned to them.
+
+### Create a Custom Role
+
+1. Open the [Roles page](https://os.agno.com/settings/roles) in the control plane.
+2. Define a role name and select the scopes it grants.
+3. Save the role.
+
+### Assign a Role to a User
+
+Open the [Organization settings page](https://os.agno.com/settings/organization) and assign the role to a user.
+
+<video
+  autoPlay
+  muted
+  controls
+  className="w-full aspect-video"
+  src="/videos/roles.mp4"
+></video>
+
 ## JWT Token Structure
 
 Your JWT tokens should include:
diff --git a/videos/roles.mp4 b/videos/roles.mp4
new file mode 100644
index 00000000..5d85db6e
Binary files /dev/null and b/videos/roles.mp4 differ