docs: document organizations

content/docs/platform/meta.json

@@ -9,6 +9,8 @@
 		"error-tracking",
 		"retention",
 		"notebooks",
+		"---Organizations---",
+		"...organizations",
 		"---Guides---",
 		"...guide",
 		"---Chart Editor---",

content/docs/platform/organizations/index.mdx

@@ -0,0 +1,73 @@
+---
+title: Organizations
+description: Share projects with your team in a common workspace.
+icon: BuildingComplex
+---
+
+import { Cards, Card } from "fumadocs-ui/components/card";
+
+An organization is a shared workspace. Everyone in it sees the same projects, and their [role](/platform/organizations/roles) decides what they can change.
+
+Every FastStats account also has a **personal workspace**. Projects in your personal workspace are only visible to you. To work on a project with other people, create it in an organization or [move it there](#moving-projects-between-workspaces).
+
+<Cards>
+	<Card href="/platform/organizations/members" title="Members & Invitations">
+		Invite people, change their roles, and remove them.
+	</Card>
+	<Card href="/platform/organizations/roles" title="Roles & Permissions">
+		Built-in roles, what each one can do, and custom roles.
+	</Card>
+</Cards>
+
+## Creating an organization
+
+1. Open the workspace switcher at the top of the sidebar
+2. Choose **Create organization**
+3. Enter a name and, optionally, upload a logo (an image up to 5 MB; animated images such as GIFs work too)
+
+You become the organization's **Owner**. Invite your team from the [Invitations](/platform/organizations/members#inviting-people) tab.
+
+## Switching workspaces
+
+Use the workspace switcher at the top of the sidebar to move between your personal workspace and the organizations you belong to. New projects are created in the workspace that's active when you create them.
+
+## Moving projects between workspaces
+
+To move a project, open its **Settings**, scroll to the danger zone, and click **Transfer** under **Transfer ownership**. You can move it to your personal workspace or to any organization you're a member of.
+
+Moving a project requires the **Move** permission on projects, which only Owners have by default, and permission to create projects in the workspace you're moving it to.
+
+## Organization settings
+
+Open an organization from the **Organizations** page to manage it. The **Settings** tab has:
+
+| Setting                     | Description                                                                  |
+| --------------------------- | ---------------------------------------------------------------------------- |
+| Organization name           | The display name shown across FastStats.                                     |
+| Logo                        | Shown in the workspace switcher. Animated images such as GIFs are supported. |
+| Workspace URL               | The slug used in links to the organization. Contact support to change it.    |
+| Organization ID             | Use it when contacting support or calling the API.                           |
+| Require 2FA for all members | Members without two-factor authentication lose access until they turn it on. |
+
+Changing settings requires the **Edit** permission on the organization (Admins and Owners).
+
+### Requiring two-factor authentication
+
+When **Require 2FA for all members** is on, members who haven't set up two-factor authentication on their account can't open the organization's projects, and can't invite, remove, or change the roles of other members. They get access back as soon as they turn on 2FA in their account settings.
+
+<Callout variant="info">
+	Turn on 2FA for your own account before you require it, so you don't lock
+	yourself out of member management.
+</Callout>
+
+## Transferring ownership
+
+Only an Owner can transfer an organization. In the **Danger zone** tab, choose **Transfer organization**, pick an existing member to become the new Owner, and type the organization's name to confirm. You become an Admin.
+
+The person you transfer to must already be a member. If you're the only member, [invite someone](/platform/organizations/members#inviting-people) first.
+
+## Deleting an organization
+
+Deleting an organization permanently removes it and everything in it, and can't be undone. Before you can delete it, **delete or move every project** in the organization.
+
+Only Owners can delete an organization, from the **Danger zone** tab.

content/docs/platform/organizations/members.mdx

@@ -0,0 +1,46 @@
+---
+title: Members & Invitations
+description: Invite people to an organization, change their roles, and remove them.
+icon: Users
+---
+
+The **Members** tab lists everyone in the organization with their role. Owners are listed first, then Admins, then everyone else. Use the search box to filter by name or email.
+
+## Inviting people
+
+Admins and Owners can invite people from the **Invitations** tab:
+
+1. Click **Invite member**
+2. Enter their email address
+3. Pick the [role](/platform/organizations/roles) they'll have when they join
+4. Click **Send Invite**
+
+The invitee gets an email with a link to accept the invitation. If they already have a FastStats account, they also see it in their in-app notifications.
+
+Invitations expire after 48 hours. The **Invitations** tab shows each pending invitation and when it expires. To withdraw one, open its menu and choose **Cancel invite**.
+
+## Accepting an invitation
+
+Opening the invitation link shows the organization, the role you've been offered, the email address it was sent to, and when it expires. Click **Accept invitation** to join, or **Decline**.
+
+You need a FastStats account to accept:
+
+- **If you have one**, sign in with the email address the invitation was sent to
+- **If you don't**, choose **Create account**. The invitation lets you sign up even while sign-ups are invite-only
+
+If the organization [requires two-factor authentication](/platform/organizations#requiring-two-factor-authentication), turn on 2FA for your account before accepting.
+
+## Changing a member's role
+
+Admins and Owners can change roles. On the **Members** tab, open the member's menu, choose **Change role**, and pick the new role.
+
+An Owner's role can't be changed directly. [Transfer ownership](/platform/organizations#transferring-ownership) to someone else first.
+
+## Removing a member
+
+On the **Members** tab, open the member's menu and choose **Remove member**. They lose access to the organization and all of its projects right away.
+
+- You can't remove yourself from this menu
+- An Owner can't be removed. Transfer ownership first
+
+Removing a member doesn't delete anything they created. Their dashboards, charts, and notebooks stay in the organization.

content/docs/platform/organizations/meta.json

@@ -0,0 +1,4 @@
+{
+	"title": "Organizations",
+	"pages": ["index", "members", "roles"]
+}

content/docs/platform/organizations/roles.mdx

@@ -0,0 +1,95 @@
+---
+title: Roles & Permissions
+description: Built-in roles, what each one can do, custom roles, and API key permissions.
+icon: ShieldCheck
+---
+
+Every member of an organization has a role. The role decides what they can see and change in the organization's projects, and whether they can manage the organization itself.
+
+Permissions apply to every project in the organization. In your personal workspace, you always have full access to your own projects.
+
+## Built-in roles
+
+| Role   | For                                                                                                                                      |
+| ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Viewer | People who only need to look at analytics. Read-only access to every project.                                                            |
+| Editor | People who build things. Create and edit projects, dashboards, charts, and more.                                                         |
+| Admin  | People who run the organization. Everything an Editor can do, plus deleting data and managing members, invitations, roles, and settings. |
+| Owner  | Everything an Admin can do, plus moving projects, transferring the organization, and deleting it.                                        |
+
+The person who creates an organization is its Owner. Built-in roles can't be edited or deleted.
+
+## Permissions
+
+Each permission is an action on a resource. This table shows what each built-in role can do.
+
+| Resource                 | Viewer | Editor             | Admin                        | Owner                              |
+| ------------------------ | ------ | ------------------ | ---------------------------- | ---------------------------------- |
+| Projects                 |        | Create, Edit       | Create, Edit, Delete, Export | Create, Edit, Delete, Export, Move |
+| Dashboards               | View   | All                | All                          | All                                |
+| Insights                 | View   | All                | All                          | All                                |
+| Session replays          | View   | View, Edit         | All                          | All                                |
+| Web vitals               | View   | View               | View                         | View                               |
+| Error tracking           | View   | View, Edit         | All                          | All                                |
+| Data sources             | View   | View, Create, Edit | All                          | All                                |
+| Download analytics       | View   | All                | All                          | All                                |
+| Network rules            | View   | View               | All                          | All                                |
+| Feature flags            | View   | All                | All                          | All                                |
+| Feature flag evaluations |        | Evaluate           | Evaluate                     | Evaluate                           |
+| Segments                 | View   | All                | All                          | All                                |
+| Source map uploads       |        | Upload             | Upload                       | Upload                             |
+| Event explorer           | View   | View               | View                         | View                               |
+| API keys                 |        | All                | All                          | All                                |
+| Organization             |        |                    | Edit                         | Edit, Delete                       |
+| Invitations              |        |                    | Create, Cancel               | Create, Cancel                     |
+| Members                  |        |                    | Edit, Remove                 | Edit, Remove                       |
+| Roles                    |        |                    | All                          | All                                |
+
+**All** means every action the resource has. Some things in FastStats are covered by another resource's permissions:
+
+- **Insights** cover charts, funnels, Sankeys, retention, paths, and event markers
+- **Dashboards** also cover [notebooks](/platform/notebooks) and folders on the Dashboards page
+
+When you don't have permission for an action, FastStats shows it with a lock icon. Hover it, or tap it on mobile, to see why it isn't available.
+
+## Custom roles
+
+If the built-in roles don't fit, Admins and Owners can create custom roles from the **Roles** tab of the organization:
+
+1. Click **Create custom role**
+2. Enter a name. Names are lowercase; spaces are turned into hyphens
+3. Tick the permissions the role should have, per resource and action
+4. Click **Create role**
+
+Custom roles show up next to the built-in ones when you [invite someone](/platform/organizations/members#inviting-people) or [change a member's role](/platform/organizations/members#changing-a-members-role). Edit or delete a custom role from its row on the **Roles** tab.
+
+<Callout variant="info">
+	There's no permission to add members directly. People only join through
+	invitations, so a custom role can grant **Create** on invitations instead.
+</Callout>
+
+## API keys
+
+API keys let scripts and services call the [FastStats API](/api) with the `x-api-key` header. There are two kinds:
+
+| Kind             | Created in                          | Prefix     | Can access                          | Rate limit         |
+| ---------------- | ----------------------------------- | ---------- | ----------------------------------- | ------------------ |
+| Organization key | The organization's **API keys** tab | `fs_org_`  | Projects in that organization       | 1,200 requests/min |
+| Personal key     | Your account settings               | `fs_user_` | Projects in your personal workspace | 600 requests/min   |
+
+When you create a key, you choose:
+
+- **Permissions:** pick them individually, or start from a preset (**Read-only**, **Editor**, **Admin**, or **Full access**) and adjust
+- **Project access:** all current and future projects, or only the projects you select
+- **Expiration:** a number of days, or never
+
+<Callout variant="info">
+	An API key can never do more than the person who creates it. You can only
+	grant a key permissions that you have yourself, and only give it access to
+	projects you can access. To create a key with broader access, ask someone
+	whose role has that access.
+</Callout>
+
+The key is shown once, right after you create it. Copy it and store it somewhere safe.
+
+The **API keys** tab is only visible to members whose role can view API keys. Editors, Admins, and Owners can create and revoke organization keys by default.