docs: document Warp's native workspaces model

.agents/references/terminology.md

@@ -143,6 +143,23 @@ For the summary of the most critical terms (core features, Automation Platform t
 
 - **Workflow** / **Workflows** — Saved, runnable workflows in Warp Drive (often multi-step command sequences).
 
+## Team and workspace terms
+
+- **workspace** — Warp's top-level organizational unit for enterprise accounts. It groups teams under one company account with shared roles, billing, SSO, and settings. See [Workspaces](/enterprise/team-management/workspaces/).
+  *Usage note:* Lowercase common noun, like "team." Distinguish it from a team's shared workspace in **Warp Drive** and a **Slack workspace**. If the context is unclear, write "Warp workspace" or "Slack workspace."
+
+- **Member** (workspace role) — The default workspace role: uses Warp within whatever teams they belong to and the settings admins configure. See [Workspace roles](/enterprise/team-management/workspaces/#workspace-roles).
+
+- **Admin** (workspace role) — Manages workspace membership, billing, and settings. Can view and manage every team in the workspace, including teams they don't belong to. A workspace can have any number of admins. See [Workspace roles](/enterprise/team-management/workspaces/#workspace-roles).
+
+- **Owner** (workspace role) — The workspace's single highest-privilege role. Has every admin capability, plus the ability to transfer ownership to another member. Exactly one per workspace. See [Workspace roles](/enterprise/team-management/workspaces/#workspace-roles).
+
+- **Open** (team visibility) — A team any workspace member can see and join immediately. See [Teams inside a workspace](/enterprise/team-management/workspaces/#teams-inside-a-workspace).
+
+- **Hidden** (team visibility) — A team that doesn't appear in team discovery; an admin has to add members directly. See [Teams inside a workspace](/enterprise/team-management/workspaces/#teams-inside-a-workspace).
+
+- **unassigned user** — A workspace member who doesn't belong to a team. Workspace admins manage unassigned users and can set a separate per-user spend limit for them. See [Unassigned users](/enterprise/team-management/workspaces/#unassigned-users).
+
 ## Automation Platform terminology
 
 Renamed from "Oz" on 2026-08-18. Two surfaces keep the Oz name until 2026-10-06

src/content/docs/enterprise/security-and-compliance/sso.mdx

@@ -5,7 +5,7 @@ description: >-
   across your organization.
 ---
 
-Warp uses SSO to authenticate users and control access to your organization's Warp team. This guide covers configuring SSO, testing your setup, and managing user access through your identity provider.
+Warp uses SSO to authenticate users and control access to your Warp workspace. Configure SSO at the workspace level, then manage access through your identity provider.
 
 ## Supported identity providers
 
@@ -19,7 +19,7 @@ Warp supports the following identity providers:
 
 ## SSO enforcement and session management
 
-* **SSO enforcement** - Admins can require SSO for all team members, preventing login via other methods.
+* **SSO enforcement** - Workspace admins can require SSO for all workspace members, preventing login via other methods.
 * **Multi-factor authentication** - MFA is enforced through your identity provider's policies. Warp respects MFA requirements configured in Okta, Microsoft Entra ID, Google Workspace, etc.
 * **Session management** - Configurable session timeouts and re-authentication policies through your identity provider.
 
@@ -28,18 +28,16 @@ Warp supports the following identity providers:
 SSO is configured through [WorkOS](https://workos.com) in coordination with Warp's team:
 
 1. Contact your Warp account team or [enterprise support](https://www.warp.dev/contact-sales) to initiate SSO setup.
-2. Warp creates an organization for your team in WorkOS and sets your team domain.
+2. Warp creates an organization for your workspace in WorkOS and sets its domain.
 3. Your IT admin receives an email invite from WorkOS.
 4. Follow the WorkOS setup wizard to connect your identity provider (configure SAML attributes or OAuth scopes, provide your SSO URL and certificate).
-5. Once complete, team members can log in via **Continue with SSO** on the [Warp login page](https://app.warp.dev/login).
+5. Once complete, workspace members can log in via **Continue with SSO** on the [Warp login page](https://app.warp.dev/login).
 
-:::note
 After enabling SSO, existing users who signed up with email or OAuth need to link their accounts. See [Linking existing accounts](#linking-existing-accounts) below.
-:::
 
 ## Testing SSO
 
-Before rolling out to your team:
+Before rolling out SSO to your workspace:
 
 1. Open an incognito/private browser window.
 2. Navigate to the [Warp login page](https://app.warp.dev/login).
@@ -55,12 +53,12 @@ Warp cannot be launched directly from your SSO provider's app portal (e.g., Okta
 
 Warp supports SCIM for user lifecycle management. Provisioning works through Just-In-Time (JIT) provisioning combined with SSO and domain capture:
 
-* **User provisioning** - Add users to the Warp application in your identity provider. Once they sign in via SSO, they are automatically added to your Warp team.
-* **Domain auto-join** - Users who sign in with SSO from your configured domain are automatically joined to your team. See [Domain auto-join](#domain-auto-join) for setup details.
+* **User provisioning** - Add users to the Warp application in your identity provider. Once they sign in via SSO, they are automatically added to your Warp workspace.
+* **Domain auto-join** - Users who sign in with SSO from your configured domain are automatically joined to your workspace. See [Domain auto-join](#domain-auto-join) for setup details.
 * **User deprovisioning** - Removing a user from the Warp application in your identity provider prevents future SSO logins. Existing sessions are not immediately revoked.
 
 :::note
-Warp does not currently support SCIM group sync. User provisioning is handled via JIT — users appear in your Warp team after their first SSO login, not at the time they are assigned in your identity provider.
+Warp does not currently support SCIM group sync. User provisioning is handled via JIT — users appear in your Warp workspace after their first SSO login, not at the time they are assigned in your identity provider.
 :::
 
 ## Linking existing accounts
@@ -74,13 +72,11 @@ Users who created a Warp account before your organization enabled SSO need to li
 
 ## Domain auto-join
 
-Domain auto-join allows users from your organization to automatically join your Warp team after SSO authentication.
+Domain auto-join allows users from your organization to automatically join your Warp workspace after SSO authentication.
 
-:::note
-Domain configuration is set up by the Warp team during onboarding. Contact your Warp account team to configure or update your team domain.
-:::
+Domain configuration is set up by the Warp team during onboarding. Contact your Warp account team to configure or update your workspace domain.
 
-Once your team domain is configured, users who sign in via SSO from your domain are automatically added to your Warp team.
+Once your workspace domain is configured, users who sign in via SSO from that domain are automatically added to your workspace.
 
 ## Troubleshooting
 

src/content/docs/enterprise/support-and-resources/billing.mdx

@@ -76,6 +76,8 @@ Spending is tracked across all payment types (add-on credits, pay-as-you-go usag
 Team-wide spending limits (cloud, local, and total) are also available on Warp's self-serve paid plans through admin-managed Add-on credit settings. **Per-user spending limits are Enterprise-only.** For deeper visibility into how individual users consume credits, see the [Enterprise Analytics API](/enterprise/enterprise-features/analytics-api/).
 :::
 
+Multi-team workspaces can also have a workspace-level cap above their team limits. See [Workspace spend limits](/enterprise/team-management/workspaces/#workspace-spend-limits).
+
 #### Monthly spend alerts
 
 Warp sends alerts to administrators as team usage approaches each configured spending limit, so you can adjust caps, purchase more credits, or communicate with your team before agent usage is blocked at the cap.

src/content/docs/enterprise/team-management/admin-panel.mdx

@@ -53,6 +53,8 @@ Team members see organization-enforced settings in their personal Settings panel
 
 The Admin Panel uses a three-tier enforcement model that keeps administrators in control while allowing appropriate flexibility.
 
+In multi-team workspaces, workspace admins can enforce supported settings across all teams or let each team decide. See [Workspace settings and team settings](/enterprise/team-management/workspaces/#workspace-settings-and-team-settings).
+
 ### Setting enforcement levels
 
 **Organization enforced**
@@ -240,7 +242,7 @@ For Enterprise plans with negotiated credit pools:
 * Monitor usage by team
 * Set per-team spending limits
 
-Contact your account manager to configure advanced credit allocation.
+Contact your account manager to configure advanced credit allocation. Multi-team workspaces can also use [workspace spend limits](/enterprise/team-management/workspaces/#workspace-spend-limits).
 
 ### Sharing settings
 
@@ -319,7 +321,7 @@ After purchasing a Warp enterprise plan:
 5. **Configure BYOLLM** (optional) - Route inference through your cloud accounts.
 6. **Create shared resources** - Populate team Warp Drive with Workflows, Rules, and Prompts.
 
-See [Roles and permissions](/enterprise/team-management/roles-and-permissions/) for details on user roles and access controls.
+See [Roles and permissions](/enterprise/team-management/roles-and-permissions/) for user roles and access controls. For accounts that manage multiple teams, see [Workspaces](/enterprise/team-management/workspaces/).
 
 ### Adjusting policies for different teams
 

src/content/docs/enterprise/team-management/roles-and-permissions.mdx

@@ -7,6 +7,10 @@ description: >-
 
 Warp uses a role-based access model to control what team members can do within your organization. Admins manage team settings and enforce policies, while members use Warp's features within the boundaries admins define.
 
+:::note
+The roles on this page apply to single-team workspaces. In multi-team workspaces, [workspace roles](/enterprise/team-management/workspaces/#workspace-roles) govern company-wide access.
+:::
+
 ## User roles
 
 Warp has three user roles:
@@ -72,5 +76,6 @@ For organizations with sensitive internal processes, disable public link sharing
 
 ## Related resources
 
+* [Workspaces](/enterprise/team-management/workspaces/) - How workspace and team roles work in multi-team accounts
 * [Admin Panel](/enterprise/team-management/admin-panel/) - Configure team settings and enforce policies
 * [Getting started for developers](/enterprise/getting-started/getting-started-developers/) - Developer onboarding guide

src/content/docs/enterprise/team-management/teams.mdx

@@ -14,7 +14,7 @@ A team is a group of Warp users who collaborate together. Teams share a dedicate
 Teams are the foundation of Warp's enterprise experience — they enable centralized administration, shared configuration, and team-wide policy enforcement through the [Admin Panel](/enterprise/team-management/admin-panel/).
 
 :::note
-Each Warp user can be an admin or member of one team at a time.
+Users can belong to one team in a single-team workspace or multiple teams in a [multi-team workspace](/enterprise/team-management/workspaces/).
 :::
 
 ## Creating a team
@@ -26,6 +26,8 @@ You can create a new team in two ways:
 
 When creating a team, give it a meaningful name that represents your organization, company, or project. The person who creates the team becomes the **Team Owner**.
 
+In a multi-team workspace, workspace admins create teams from the Admin Panel. See [Teams inside a workspace](/enterprise/team-management/workspaces/#teams-inside-a-workspace).
+
 :::note
 You can rename your team at any time by going to **Settings** > **Teams**, clicking on the team name, entering the new name, and pressing `Enter`.
 :::
@@ -115,6 +117,8 @@ We recommend having at least one Team Admin in addition to the Team Owner to pre
 
 ### Permissions overview
 
+This table applies to single-team workspaces. In multi-team workspaces, only workspace admins create teams. See [Workspace roles](/enterprise/team-management/workspaces/#workspace-roles).
+
 | Action | Owner | Admin | Member |
 | --- | --- | --- | --- |
 | Create a team | ✓ | ✓ | ✓ |
@@ -147,6 +151,7 @@ For detailed information on what each role can do and how settings enforcement w
 
 ## Related resources
 
+* [Workspaces](/enterprise/team-management/workspaces/) - How teams and roles work in multi-team accounts
 * [Admin Panel](/enterprise/team-management/admin-panel/) - Configure team settings and enforce policies
 * [Roles and permissions](/enterprise/team-management/roles-and-permissions/) - Detailed permission breakdowns and settings enforcement
 * [Getting started for admins](/enterprise/getting-started/getting-started-enterprise/) - Admin onboarding guide

src/content/docs/enterprise/team-management/workspaces.mdx

@@ -0,0 +1,71 @@
+---
+title: Workspaces
+description: >-
+  Workspaces group teams under one Enterprise account with shared membership,
+  billing, SSO, and company-wide settings.
+---
+
+A workspace groups one or more teams under a single Enterprise account. Workspace admins manage membership, billing, and company-wide policies across those teams. Single Sign-On (SSO) is configured at the workspace level.
+
+## Workspaces and teams
+
+A workspace provides company-wide administration, while teams organize shared resources and team-level settings.
+
+* **Workspace level** - Billing, SSO, domain capture, and organization-wide policies apply across teams.
+* **Team level** - Members share Warp Drive resources, cloud agent runs, environments, and secrets.
+* **Membership** - A user belongs to one workspace and can belong to multiple teams within it.
+
+## Workspace roles
+
+Every workspace member has one of three roles:
+
+* **Member** - Uses Warp within their teams and the policies admins configure.
+* **Admin** - Manages workspace membership, billing, and settings. Admins can view and manage every team, including teams they don't belong to.
+* **Owner** - Has every admin capability and can transfer ownership to another member. Each workspace has one owner.
+
+In team member lists, the **Workspace admin** and **Workspace owner** badges distinguish workspace roles from team roles.
+
+## Teams inside a workspace
+
+Workspace admins create teams from the Admin Panel and choose a visibility:
+
+* **Open** - Any workspace member can see the team and join it immediately.
+* **Hidden** - The team doesn't appear in team discovery; an admin adds members directly.
+
+Workspace admins can also manage every team's membership and settings.
+
+## Joining a workspace or team
+
+Workspace admins add users through invitations or domain capture:
+
+* **Workspace invite links** - Add a user to the workspace and let them choose an Open team.
+* **Team invite links** - Add a user to an Open team and its workspace.
+* **Email invites** - Add a user directly to a workspace or team. Admins add users to Hidden teams this way.
+* **Domain capture** - Automatically adds users who sign up with a verified company domain.
+* **Team discovery** - Shows Open teams to unassigned users in the Warp app under **Settings** > **Teams**.
+
+## Unassigned users
+
+An unassigned user belongs to the workspace but not to a team. Workspace admins can manage unassigned users and set a separate per-user spend limit for them in the Admin Panel.
+
+Unassigned users cannot start cloud agent or factory runs until they join a team. Workspace-level billing and policies still apply to them.
+
+## Workspace settings and team settings
+
+Workspace admins configure company-wide policies in the [Admin Panel](/enterprise/team-management/admin-panel/). For supported settings, they can enforce a value across the workspace or select **Respect Team Setting** to let each team decide.
+
+SSO and domain capture apply at the workspace level. When a workspace admin enforces a setting, team admins see it as locked.
+
+## Workspace spend limits
+
+Workspace admins can set monthly limits for total, local agent, and cloud agent spending. They can also set a separate per-user limit for unassigned users. Team and individual limits remain independent, and the first applicable limit reached blocks further usage within its scope.
+
+{/* VERIFY: confirm what team admins see when a workspace limit blocks usage before documenting that notice */}
+
+## Related pages
+
+* [Team management](/enterprise/team-management/teams/) - Create and manage teams
+* [Admin Panel](/enterprise/team-management/admin-panel/) - Configure settings enforced across a workspace or team
+* [Roles and permissions](/enterprise/team-management/roles-and-permissions/) - Team-level roles and what each can do
+* [Single Sign-On (SSO)](/enterprise/security-and-compliance/sso/) - Configure authentication for a workspace
+* [Enterprise billing](/enterprise/support-and-resources/billing/) - Credit pools, spend limits, and billing management

src/content/docs/knowledge-and-collaboration/admin-panel.mdx

@@ -15,6 +15,8 @@ The [Admin Panel](https://app.warp.dev/admin/) provides team administrators with
 Admin Panel access is restricted to team administrators. Right now, only the creator of a team is the designated admin. If your admin has set up styles that override user preferences, you will not be able to control them inside of Warp, and you'll see a note that your admin has configured this setting.
 :::
 
+In multi-team workspaces, workspace admins configure supported settings across all teams. See [Workspace settings and team settings](/enterprise/team-management/workspaces/#workspace-settings-and-team-settings).
+
 **Key features:**
 
 * **AI Settings** - Control agent autonomy, permissions, and allowlists across your team

src/content/docs/knowledge-and-collaboration/teams.mdx

@@ -5,14 +5,14 @@ description: >-
 ---
 import VideoEmbed from '@components/VideoEmbed.astro';
 
-A Warp team is a group of users who collaborate through a shared workspace in Warp Drive. Teams share Workflows, Notebooks, Prompts, Rules, and Environment Variables, with role-based permissions for admins and members. Each Warp user can belong to one team at a time.
+A Warp team is a group of users who collaborate through a shared workspace in Warp Drive. Teams share Workflows, Notebooks, Prompts, Rules, and Environment Variables, with role-based permissions for admins and members.
 
 ## What is a team?
 
 A team is a group of Warp users who can collaborate on the command line together. Warp teams can share a dedicated workspace in Warp Drive. [Learn about pricing](https://www.warp.dev/pricing) and see our [Pricing FAQ](/support-and-community/plans-and-billing/pricing-faqs/).
 
 :::note
-Currently, each Warp user can only be an admin or member of one team at a time.
+Users can belong to multiple teams when their Enterprise account uses a [multi-team workspace](/enterprise/team-management/workspaces/).
 :::
 
 <VideoEmbed url="https://www.youtube.com/watch?v=8UmreUTTrkg&start=199s&end=277s" title="Teams Demo" />
@@ -108,3 +108,5 @@ If you're a Team admin, and you choose to [delete your Warp](/support-and-commun
 | Delete a team | ✓ | |
 | Transfer admin | ✓ | |
 | [Manage billing](/support-and-community/plans-and-billing/pricing-faqs/#how-do-i-manage-my-billing) | ✓ | |
+
+Multi-team workspaces use [workspace roles](/enterprise/team-management/workspaces/#workspace-roles) for company-wide administration.

src/sidebar.ts

@@ -826,6 +826,7 @@ export const sidebarTopics: StarlightSidebarTopicsUserConfig = [
 				{
 					label: 'Team management',
 					items: [
+						{ slug: 'enterprise/team-management/workspaces', label: 'Workspaces' },
 						'enterprise/team-management/teams',
 						{ slug: 'enterprise/team-management/admin-panel', label: 'Admin panel' },
 						{ slug: 'enterprise/team-management/roles-and-permissions', label: 'Roles and permissions' },