docs(teams): revamp to include organizations

src/content/docs/teams.mdx

@@ -1,46 +1,138 @@
 ---
 title: Teams
-description: Working with a team of developers
+description: Learn how to manage teams and organizations in Shorebird
 ---
 
-Shorebird Teams tier and higher allows adding an unlimited number of
-collaborators to an app. Shorebird free "Hobby" users can upgrade
-to the Teams tier to add collaborators via a link in the
-[Shorebird console](https://console.shorebird.dev).
+Shorebird's Pro tier and unlocks new features for collaborating with your team
+include:
 
-## Upgrading to Teams
+- Create unlimited organizations
+- Add unlimited members to your organizations
+- Manage roles for your organization members
+- Add unlimited collaborators to an individual app
+- Manage roles for your app collaborators
+
+Shorebird free "Hobby" users can upgrade to the Pro tier to add these features
+via the account settings page in the [Shorebird console](https://console.shorebird.dev/account).
+
+## Upgrading to Pro
 
 You can manage your account and billing at any time via
 https://console.shorebird.dev/account
 
 There is an "Edit" drop-down there, and from within that an "Upgrade Account"
-option which will present you a pop-up dialog and allow you to chose the plan
-you wish to upgrade to.
-
-There is a slider control at the bottom of the dialog which allows choosing
-different plan levels.
+option which will present you a pop-up dialog and allow you to upgrade to the "Pro" plan.
 
 If you do not see the plan you're expecting, please reach out to
 [email protected] we'd be happy to work with you.
 
-Once you've upgraded to a Teams plan, you have the ability to manage
-Collaborators on a per-app level.
+Once you've upgraded to the Pro plan, you have the ability to use the above
+features.
+
+## Creating an Organization
+
+Organizations are a way to group apps and team members together. To create an
+organization, visit the Shorebird console and click the account dropdown in the
+top left corner. From there, click the "+" button next to "Organizations".
+
+![Create
+Organization](https://github.com/user-attachments/assets/6117e85f-ff07-4ffa-9683-3b4543f252d1)
+
+This will automatically create a new organization called "My Organization". You
+can head over to the organization's settings to change the name:
+
+![Rename
+Organization](https://github.com/user-attachments/assets/c33eda7c-bdd3-4ef2-ab0e-cbcaadbdd99f)
+
+## Managing Members
+
+To add one or more members to your organization, visit the organization's
+settings and click the "Add member" button.
+
+![Add
+Member](https://github.com/user-attachments/assets/584703fc-d20d-49b2-8358-b3b187c7fefc)
+
+You can also edit a member's role or remove them from the organization from the
+same organization settings page.
+
+![Organization Settings with new
+Member](https://github.com/user-attachments/assets/4936b211-23d8-4a44-90e6-06fab421a4f4)
+
+## Managing Organization Apps
+
+Organizations can have multiple apps associated with them. You can either
+transfer existing apps to an organization or create new apps within the
+organization directly.
+
+To transfer an existing app to an organization, visit the app's settings and
+click the "Transfer app" button. You can then select the organization you want
+to transfer the app to from the dropdown.
+
+![Transfer
+App](https://github.com/user-attachments/assets/9d7c5428-ebfd-4c9c-9777-4ca06da8d962)
+
+To create a new app within an organization, select the organization when running
+`shorebird init`:
+
+![Shorebird Init with
+Organization](https://github.com/user-attachments/assets/6a07fb1f-1fc6-4b41-9df8-60a50c42b475)
+
+## Organization Roles
+
+Organization roles apply to all apps within the organization and can be managed
+via the organization settings page in the Shorebird console.
+
+If you have any questions about access control for your app, please do not
+hesitate to reach out to [email protected].
+
+### Organization Member
+
+New members added to an organization are assigned the "Member" role by default.
+
+Members can:
+
+- Read information for all apps within the organization
+- View collaborators on all apps within the organization
+- Create releases and patches for all apps within the organization
+- View insights for all apps within the organization
+
+### Organization Admin
+
+Organization Admins can:
+
+- Everything a Member can do
+- Add and Remove Members for the organization
+- Delete Apps within the organization
+- Delete Releases within the organization
+
+### Organization Owner
+
+There is only one owner per organization (the person who created the
+organization) and they have full control over the organization and all apps
+within it.
+
+The owner can:
+
+- Everything an Admin can do
+- Manage the billing information for the organization
 
 ## Managing Collaborators
 
-Collaborators can be managed on the Shorebird console. To add a collaborator,
-from your app's page:
+Per app collaborators can also be added and managed via the Shorebird console.
+To add a collaborator, from your app's page:
 
 1. Select the "Collaborators" tab.
 2. Click "Add people".
-3. Enter the email address of the person you would like to add as a collaborator.
-   1. Note that the email address must be associated with an existing Shorebird account.
+3. Enter the email address of the person you would like to add as a
+   collaborator.
+   1. Note that the email address must be associated with an existing Shorebird
+      account.
 4. Click "Add Collaborator".
 
 Existing collaborators can be removed by clicking the trash icon next to their
 email address.
 
-## App Roles
+## Collaborator Roles
 
 _Roles are per-app._ Each account can create Apps tied to that account. Once an
 App is created, access to that app can be shared. If you have any questions
@@ -65,79 +157,11 @@ The Admin role can:
 - Everything a Developer can do
 - Add and Remove Developers for an App
 - Delete Apps
-- Delete Releases
-  Admin permissions cannot currently be modified in the console. Please email us
-  if you need to add/remove Admins from an app.
-
-#### Adding an Admin
-
-To make a developer an admin on your app, first make sure they have created
-a Shorebird account. You can then add them as a collaborator via the console
-for any apps you wish. After that, to make them an admin, you'll currently need
-to reach out to us at [email protected] and we're happy to adjust their
-status from "Developer" to "Admin" on any apps you desire.
-
-See https://github.com/shorebirdtech/shorebird/issues/2477
-
-## Account Owner
-
-Only the account owner can create apps tied to that account or change the
-billing information for that account. When an App is created it is tied to an
-Owner account. Individual Apps can be moved between accounts (have their
-Owner changed) by contacting us at [email protected].
-
-## Sharing Multiple Apps
-
-Each app maintains a separate list of collaborators. If you need to share
-multiple apps with a team, you will need to add each app separately. We plan
-to add more robust teams support later this year.
-https://github.com/shorebirdtech/shorebird/issues/739
+- Delete Releases Admin permissions cannot currently be modified in the console.
+  Please email us if you need to add/remove Admins from an app.
 
 ## Transferring Ownership
 
-We do not currently have an automated way to transfer ownership of an app.
-However you're welcome to [contact us](mailto:[email protected]) and we
-will be happy to help you transfer ownership of an app. Please email
-us from the account you're transferring from to help us know it's you. The
-account you're transferring to must have an account with Shorebird, which
-can be created by clicking through the OAuth flow at
-https://console.shorebird.dev with the Google or Microsoft account in question.
-
-https://github.com/shorebirdtech/shorebird/issues/1225
-
-# FAQ
-
-## Another person purchased Shorebird, but they want me to create the apps?
-
-Shorebird currently only has app-level sharing, rather than account-level sharing
-so it's not possible to set up billing for a "group" of users, but when an app
-is created it is associated with an "owner" account, to which installs are billed.
-We plan to add account-level sharing later this year:
-https://github.com/shorebirdtech/shorebird/issues/739
-
-To create apps which are billed to someone else, there are 3 options:
-
-1. If this person is able to create the apps (run `shorebird init` in the
-   codebase), then those apps will then be associated with their account and
-   they can set per-app permissions accordingly, as per the above instructions.
-
-2. It's possible for us to manually associate their Stripe Customer with your
-   account, so that you can create and administer access to apps but have the
-   billing sent to their Stripe account. This is probably the most common
-   solution we've deployed. This allows you to create as many apps now or in the
-   future without needing the card holder to take further action.
-
-3. It is also possible for you to create any needed apps and then afterwards, we
-   can then transfer the apps to their account for them to manage, including
-   giving you "Admin" if desired. This means any time you'd like to create
-   another app billed to their account you'll need to reach out to
-   [email protected], but it's very quick for us to move apps when needed.
-
-For either option 2 or 3, please reach out to [email protected] and
-tell us which option you would like to pursue and the email addresses associated
-with the accounts, and we would be _happy_ to help. Please make sure that all
-email addresses involved already have Shorebird accounts (accounts are created when logging into https://console.shorebird.dev/ for the first time).
-
-We are aware that this is a common source confusion due to our limited sharing support at this time
-and we expect to have it addressed with a more sophisticated app sharing system
-later this year: https://github.com/shorebirdtech/shorebird/issues/739
+The easiest way to transfer app ownership is to have the desired owner create an
+organization and add the current owner to the organization. The current owner
+can then transfer the app to the organization.