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
 contact@shorebird.dev 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 contact@shorebird.dev.
+
+### 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,29 @@ 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.
+- 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 contact@shorebird.dev and we're happy to adjust their
-status from "Developer" to "Admin" on any apps you desire.
+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 contact@shorebird.dev 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 contact@shorebird.dev.
-
-## 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
+Owner account. Individual Apps can be moved between accounts (have their Owner
+changed) by contacting us at contact@shorebird.dev or by being transferred to an
+organization (see below).
 
 ## Transferring Ownership
 
-We do not currently have an automated way to transfer ownership of an app.
-However you're welcome to [contact us](mailto:contact@shorebird.dev) 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
-   contact@shorebird.dev, but it's very quick for us to move apps when needed.
-
-For either option 2 or 3, please reach out to contact@shorebird.dev 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.