docs(rbac): split Roles & Permissions into three pages

src/lib/navigation.ts

@@ -790,7 +790,14 @@ export const tabNavigation: NavTab[] = [
               { title: 'Usage Summary', href: '/docs/admin-settings/usage-summary' },
             ]
           },
-          { title: 'Roles & Permissions', href: '/docs/roles-and-permissions' },
+          {
+            title: 'Roles & Permissions',
+            items: [
+              { title: 'Overview', href: '/docs/roles-and-permissions' },
+              { title: 'Manage access', href: '/docs/roles-and-permissions/guides/manage-access' },
+              { title: 'Permission reference', href: '/docs/roles-and-permissions/reference/permissions' },
+            ]
+          },
           {
             title: 'Billing',
             items: [

src/pages/docs/admin-settings/api-keys.mdx

@@ -1,60 +1,84 @@
 ---
-title: "API Keys: Create & Manage Credentials"
-description: "Create, copy, and rotate FI_API_KEY and FI_SECRET_KEY credentials for authenticating with Future AGI Python and TypeScript SDKs."
+title: "API Keys"
+description: "Creating and rotating the key and secret your SDK authenticates with"
 ---
 
-## About
+API keys authenticate your application with Future AGI. A pair is an API Key (`FI_API_KEY`) and a Secret Key (`FI_SECRET_KEY`), and you need one for every way into the platform: the Python and TypeScript SDKs, the Java and C# SDKs, any OpenTelemetry based instrumentation, and the REST API.
 
-API keys authenticate your application with Future AGI. Each key pair consists of an API Key (`FI_API_KEY`) and a Secret Key (`FI_SECRET_KEY`). You need these to use the Python SDK, TypeScript SDK, or REST API.
+Owners, Admins and Workspace Admins can open this page. For everyone else it is not in the sidebar and its address returns a 404. See [Roles & Permissions](/docs/roles-and-permissions).
 
-Access: **Owner** only.
+Every organization is created with one key already in the list, named `system_org_key`.
 
-## How to
+<Warning>
+**A key belongs to the workspace you have open when you create it.** Traces sent with it land there, and **Build > Keys** only ever lists the keys of your current workspace. The dialog says none of this and offers no workspace to pick, so switch to the workspace you want the key for before you create it.
+
+If the page says *No keys has been added yet* and you know you made one, you are standing in a different workspace. Switch and look again.
+</Warning>
+
+That binding holds for traces and nothing else. Other API and SDK calls made with the same key can name a different workspace on the request, and you get it as long as that workspace is in the same organization and you have access to it. If you are separating teams, the key's workspace is not what keeps them apart.
+
+## Create a key
 
 <Steps>
-  <Step title="Open Settings">
-    Navigate to **Settings > API Keys** at [https://app.futureagi.com/dashboard/settings/api_keys](https://app.futureagi.com/dashboard/settings/api_keys).
+  <Step title="Open the Keys page">
+    In the left sidebar, find the **Build** section and click **Keys**, or go straight to [https://app.futureagi.com/dashboard/keys](https://app.futureagi.com/dashboard/keys).
+  </Step>
+  <Step title="Check which workspace you are in">
+    The switcher at the top of the sidebar shows it. The key you are about to make belongs to whichever workspace that is.
   </Step>
   <Step title="Create a new key">
-    Click **Add API Key**. Enter a name for the key.
+    Click **Add API Key**. The dialog asks for a name and nothing else.
   </Step>
   <Step title="Copy your keys">
-    Copy both the API Key and Secret Key. The Secret Key is only shown once at creation time.
+    You are shown an API Key and a Secret Key. Both stay masked on screen, so take each one with its copy button and store it before you close the dialog. This dialog does not come back, and there is no way to reveal a secret later. If you are creating the key for somebody else, send them both values now.
   </Step>
   <Step title="Use in your application">
     Set them as environment variables.
 
-    ```python
+    <CodeGroup>
+    ```python Python
     import os
     os.environ["FI_API_KEY"] = "YOUR_API_KEY"
     os.environ["FI_SECRET_KEY"] = "YOUR_SECRET_KEY"
     ```
 
-    ```typescript
+    ```typescript TypeScript
     process.env.FI_API_KEY = "YOUR_API_KEY";
     process.env.FI_SECRET_KEY = "YOUR_SECRET_KEY";
     ```
+    </CodeGroup>
   </Step>
 </Steps>
 
-## Managing Keys
+## Managing keys
 
-| Action | How |
-|--------|-----|
-| View keys | API Key is visible in the table. Secret Key is masked. |
-| Copy a key | Click the copy icon next to the key. |
-| Delete a key | Click the delete icon. This is permanent and cannot be undone. |
-| Rotate keys | Delete the old key and create a new one. Update your application with the new credentials. |
+The table lists each key with its name, a masked API Key and Secret Key, who created it, and when. Every row carries a menu with two actions, and both ask you to confirm first.
+
+**Disable Key** turns off the API Key and the Secret Key together. The row gains a **Disabled** badge, the menu changes to **Re-enable key**, and Owners, Admins and Workspace Admins can all do it.
+
+**Delete Key** removes the API Key and the Secret Key permanently. It cannot be undone, and only an Owner can do it.
 
 <Warning>
-Deleting a key immediately revokes access for any application using it. Make sure to update your code before deleting.
+**Delete Key** appears for everyone who can open this page, but only an Owner's goes through. An Admin or a Workspace Admin gets the confirmation and then **You are not authorized to access this resource**, and the key stays in the list.
 </Warning>
 
 <Tip>
-Never commit API keys to version control. Use environment variables or a secret manager.
+**To rotate a key:** create the replacement, update your application, then **disable** the old key rather than deleting it. If something you forgot about was still using it, re-enable takes one click, and disabling is the part you can do yourself without being an Owner.
+
+Both actions take effect at once, so nothing gets a grace period. And never commit a key to version control: use environment variables or a secret manager.
 </Tip>
 
-## Next Steps
+## Gateway keys are separate
+
+The keys on this page are platform API keys. The Agent Command Center has its own keys under **Gateway > API Keys**, and those are reachable by anyone in the organization.
+
+## Dive deeper
 
-- [SDK & API](/docs/sdk)
-- [Roles & Permissions](/docs/roles-and-permissions)
+<CardGroup cols={2}>
+  <Card title="Installation" icon="rocket" href="/docs/sdk">
+    Install the SDK and send your first call with these keys
+  </Card>
+  <Card title="Roles & Permissions" icon="scale-balanced" href="/docs/roles-and-permissions">
+    Who can reach the Keys page, and what each role can do there
+  </Card>
+</CardGroup>

src/pages/docs/admin-settings/user-management.mdx

@@ -1,57 +1,98 @@
 ---
-title: "User Management: Invite & Assign Roles"
-description: "Invite team members, assign Owner, Admin, Member, or Viewer roles, manage workspace access, and deactivate users in Future AGI."
+title: "User Management"
+description: "Adding people to your organization and setting what they can reach"
 ---
 
-## About
+The Members page is where you add people to your organization, change what they can reach, and remove access. For what each role can do once they are in, see [Roles & Permissions](/docs/roles-and-permissions).
 
-User Management lets you invite people to your organization, assign organization-level roles, manage workspace access, and deactivate or remove members. For details on what each role can do, see [Roles & Permissions](/docs/roles-and-permissions).
+Open it from **Settings > Members**. Every person gets one row, showing their name, organization role, workspaces, email, status, and start date.
 
-Access: **Owner** and **Admin** only.
+Owners and Admins can open this page. A Workspace Admin cannot, but can still invite people, as described below.
 
-## How to Invite Users
+## Inviting people
+
+There are two ways in.
+
+**From the Members page.** Click **Invite User** at the top right.
+
+**From the workspace switcher.** Open the switcher at the top of the sidebar and choose **Invite members**. This is the path a Workspace Admin uses, since they cannot open the Members page.
 
 <Steps>
-  <Step title="Open user management">
-    Go to **Settings > User Management**.
+  <Step title="Enter the emails">
+    One invite can cover several people at once, as a comma separated list.
   </Step>
-  <Step title="Start the invite">
-    Click **Add User** or **Invite**.
+  <Step title="Pick the organization role">
+    Owner, Admin, Member, or Viewer. The dialog describes each one above the field.
   </Step>
-  <Step title="Enter details">
-    Enter the user's email address.
+  <Step title="Pick the workspaces">
+    Choose one or more workspaces and a single workspace role that applies to all of them. At least one workspace is required.
   </Step>
-  <Step title="Assign a role">
-    Select an organization role: Owner, Admin, Member, or Viewer.
-  </Step>
-  <Step title="Assign workspaces (optional)">
-    Optionally assign them to one or more workspaces.
-  </Step>
-  <Step title="Send the invite">
-    Click **Invite**. The user receives an email invitation. Their status shows as "Pending" until they accept.
+  <Step title="Send">
+    Click **Send Invite**.
   </Step>
 </Steps>
 
-## Managing Members
+If you grant **Admin** or **Owner**, both workspace fields disappear and are replaced by *Owner and Admin roles have automatic access to all workspaces.*
+
+<Note>
+You can only grant your own role or something below it. An Admin's Organization Role list contains Admin, Member, and Viewer, and no Owner. A Workspace Admin's invite has no Organization Role field at all, so they grant a workspace role only, one of Workspace Admin, Workspace Member, or Workspace Viewer.
+</Note>
+
+The new row shows as **Pending** until the person accepts. If the email already belongs to a Future AGI account, they are added immediately and show as **Active**.
+
+A Pending row carries two actions: **Resend the invite** and **Cancel invite**. A cancelled invite comes off the list.
+
+<Warning>
+Invites expire. The invite itself is valid for 7 days, and the link inside the email stops working sooner than that. If someone says the link is dead, resend the invite from their row rather than waiting for it to lapse.
+</Warning>
 
-| Action | How |
-|--------|-----|
-| Search | Use the search bar to find members by name. |
-| Filter by status | Filter to show Active, Pending, or all members. |
-| Filter by role | Filter by Owner, Admin, Member, or Viewer. |
-| Change role | Click the edit action on a member's row. Select a new role. |
-| Remove member | Click the delete action. This revokes all access immediately. |
-| Reactivate | Deactivated users can be reactivated from the member list. |
+## Editing someone's access
 
-## Workspace Assignment
+Every row carries two actions, **Edit user info** and **Remove from organization**.
 
-When editing a user, you can assign or remove them from specific workspaces. Workspace-level roles (workspace_admin, workspace_member, workspace_viewer) are set separately from the organization role.
+**Edit user info** holds an Organization Role and a Workspace Role.
+
+| What you can change | Options |
+|---|---|
+| Organization role | Owner, Admin, Member, or Viewer |
+| Workspace role | Workspace Admin, Workspace Member, or Workspace Viewer |
+| Workspaces | Which workspaces they belong to. Appears once you set someone to Member or Viewer |
+
+Setting someone to Member or Viewer adds a required **Workspaces** field, because *Members and Viewers need explicit workspace access.* Any workspace you leave unselected is removed from them.
+
+Promoting someone to **Admin** or **Owner** gives them Workspace Admin everywhere at once, and the workspace fields disappear.
 
 <Note>
-For a detailed breakdown of what each role can access, see [Roles & Permissions](/docs/roles-and-permissions).
+You can change or remove anyone whose organization role is lower than yours, and an Owner can also change another Owner. Where you cannot, the row's menu is disabled and says why. [Manage access](/docs/roles-and-permissions/guides/manage-access#change-someones-access) covers the rest.
 </Note>
 
-## Next Steps
+## Removing and reactivating someone
+
+Removing someone from the organization ends their access immediately. Nothing they produced is lost.
+
+A few things are blocked outright:
+
+- You cannot remove yourself
+- You cannot remove or demote the last remaining Owner, so promote a second Owner first
+- You cannot remove anyone from their last workspace
+- You cannot remove an Owner or Admin from a workspace, since they reach every workspace anyway
+
+Reactivating is not something the dashboard offers. A removed person is marked Deactivated and there is no control anywhere that brings them back, so contact the Future AGI team if somebody has to be restored.
+
+## Finding people
+
+Above the table sit a **Search by name or email** box, an **All status** filter, and an **All Roles** filter.
+
+## Dive deeper
 
-- [Roles & Permissions](/docs/roles-and-permissions)
-- [Organization Settings](/docs/admin-settings/organization-settings)
+<CardGroup cols={3}>
+  <Card title="Roles & Permissions" icon="scale-balanced" href="/docs/roles-and-permissions">
+    What each organization and workspace role can reach
+  </Card>
+  <Card title="Workspace Management" icon="layer-group" href="/docs/admin-settings/workspace-management">
+    Create workspaces and manage who belongs to them
+  </Card>
+  <Card title="Organization Settings" icon="gear" href="/docs/admin-settings/organization-settings">
+    The organization name and its security policy
+  </Card>
+</CardGroup>