docs: document Warp's native workspaces model - #723
Open
warp-agent-staging[bot] wants to merge 7 commits into
Open
docs: document Warp's native workspaces model#723warp-agent-staging[bot] wants to merge 7 commits into
warp-agent-staging[bot] wants to merge 7 commits into
Conversation
Co-Authored-By: Warp <agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
@warp-agent-staging[bot] I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![warp-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Overview
This PR adds a new conceptual Workspaces page for Warp's multi-team Enterprise model, wires it into navigation, and updates related team, admin, billing, and terminology pages to point to the workspace-level model.
Concerns
- No blocking correctness, security, or spec-drift concerns found in the attached diff.
- The attached spec context contains no approved or repository spec context, so there was no material spec contract to compare against.
- Inline suggestions focus on clarifying a changed note, completing the Private team visibility behavior, and orienting the Settings path to the Warp app.
Verdict
Found: 0 critical, 0 important, 3 suggestions
Approve with nits
Comment /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Co-authored-by: warp-for-oss[bot] <277970191+warp-for-oss[bot]@users.noreply.github.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Review summary
The independent agent completed its review for this commit.
Findings
src/content/docs/enterprise/team-management/workspaces.mdx:51— [IMPORTANT] The 'Invite links' bullet claims a team invite link generally adds someone to the team, but changelog entry #15129 (2026-08-18) confirms Private and Hidden teams don't support invite-by-link, and none of the page's four VERIFY markers cover this claim. Requested change: scope the bullet to Open teams (and state how Private/Hidden teams actually add members) or add a VERIFY marker and list it under Unverified claims.src/content/docs/enterprise/team-management/workspaces.mdx:41— [SUGGESTION] The 'Private' bullet's visible sentence stops at 'Any workspace member can see the team exists' because the join-request VERIFY comment is invisible when rendered, leaving the joining mechanism unstated unlike the parallel Open/Hidden bullets. Requested change: add a clause describing the currently-confirmed joining mechanism (or explicitly note none exists yet) so the rendered bullet doesn't read as incomplete.src/content/docs/enterprise/team-management/workspaces.mdx:30— [SUGGESTION] style_lint flags new bolded role/visibility labels (Member, Owner, Private, Hidden, Workspace-enforced, Team-controlled) as unrecognized-term candidates. Requested change: extend the new 'Team and workspace terms' section in .agents/references/terminology.md to cover these terms alongside 'workspace'.
Verdict
Request changes
![warp-agent-staging[bot]](https://avatars.githubusercontent.com/in/2196476?s=60&v=4){kind=small}
Contributor
Author
There was a problem hiding this comment.
Review summary
The new Workspaces page adds the intended conceptual coverage, but it makes two source-contradicted availability and permission claims. Found: 2 critical, 0 important, 0 suggestions, 0 nits. Request changes.
Findings
src/content/docs/enterprise/team-management/workspaces.mdx:15— 🚨 [CRITICAL] This promises multi-team workspaces to the entire Enterprise plan, but the current billing configuration enablesNATIVE_WORKSPACESonly for the internalWARP_PLANtier;billing/native_workspaces_test.goalso asserts it is disabled for every other tier. The linked issue specifically requires unconfirmed availability to be omitted or clearly marked. Remove this plan-tier claim until its public availability is confirmed, or document the confirmed release scope.src/content/docs/enterprise/team-management/workspaces.mdx:60— 🚨 [CRITICAL] This says workspace admins and owners are exempt from all listed teamless restrictions, including the immediately preceding requirement to join a team before triggering cloud-agent runs. The shipped guard inlogic/user.gokeeps execution-side restrictions (cloud runs, harnesses, and member BYO credentials) role-blind; the exemption covers only oversight surfaces such as environments and managed secrets. Narrow this sentence to those exempt surfaces and state that admins and owners still need team membership to trigger runs.
Verdict
Request changes
- Fix CRITICAL: scope multi-team availability claim to 'a limited set of accounts' instead of promising it to the entire Enterprise plan (workspaces.mdx:15). - Fix CRITICAL: correct the teamless-member exemption claim so it no longer implies admins/owners can trigger cloud agent runs without joining a team (workspaces.mdx:60/62). - Fix IMPORTANT: scope the Invite links bullet to Open teams and state how Private/Hidden teams actually add members, per changelog #15129. - Complete the Private team bullet's join-mechanism sentence. - Apply the Team discovery Settings-path suggestion. - Add terminology.md entries for Member, Owner, Private, Hidden, Workspace-enforced, and Team-controlled. - Trim and tighten prose across the page per editing-pass feedback. Co-Authored-By: Warp <agent@warp.dev>
Contributor
Author
|
Addressed the two findings from the independent review pass that were posted in the review body without inline comment threads:
Both addressed on 75fdc93. |
Contributor
There was a problem hiding this comment.
Review summary
The independent agent completed its review for this commit.
Findings
src/content/docs/enterprise/team-management/workspaces.mdx:31,34,62— [IMPORTANT] The claim that a workspace admin/owner has admin-level authority over every team, including ones they don't belong to, is stated as fact with no VERIFY marker, but the only independently-checkable public source (changelog PR #15123) confirms only current-team membership management. Requested change: get engineering confirmation of cross-team authority againstspecs/workspace-admin-roles/app/src/settings_view/teams_page.rs, or add a VERIFY marker and list it under Unverified claims..agents/references/terminology.md:146-161— [SUGGESTION] The new 'Team and workspace terms' glossary section adds Member/Owner and Workspace-enforced/Team-controlled but omits sibling terms Admin (workspace role) and Delegated/Combined (setting patterns) from the same enumerations on workspaces.mdx. Requested change: add glossary entries for Admin, Delegated, and Combined for consistency.
Verdict
Request changes
Contributor
Author
There was a problem hiding this comment.
Review verdict: rejected
This final review blocks acceptance.
Blocking gates
- The required
Agent docs reviewcheck failed on the current head because the independent review signal is blocking. - This user-facing documentation change has no screenshot or video artifact in the PR that validates the rendered result against the acceptance criteria. A local preview rendered correctly, but that reviewer-side check is not PR-hosted evidence.
Documentation correctness
- The new native-workspace cross-reference incorrectly presents the deprecated Team Owner role as active in the multi-team model. Native workspaces expose workspace-level ownership and product-facing team Member/Admin roles.
Independent validation
npm run buildpassed.style_lint.py --changedcompleted; its findings were report-only existing-style/terminology diagnostics.- Internal-link, PR-risk-contract, and
feature-doccompression checks passed.
Review run: https://oz.staging.warp.dev/runs/01a0889a-f9a8-7b93-b70e-984af689dc7e
…aims Scope the Team Owner role and ownership transfer to the single-team model, state that ownership is workspace-level on a multi-team workspace, mark the cross-team admin authority claim with a VERIFY marker, and complete the workspace glossary. Co-Authored-By: Warp <agent@warp.dev>
Contributor
There was a problem hiding this comment.
Review summary
The independent agent completed its review for this commit.
Findings
src/content/docs/enterprise/team-management/workspaces.mdx:31— [IMPORTANT] The Admin role bullet states "has admin-level access to the teams in the workspace" unhedged, which is the same cross-team authority claim the VERIFY marker on line 34 exists to qualify; the PR body's cycle-2 notes claim this duplicate was dropped but it is still present, and public changelog #15123 confirms only membership management on the admin's own team. Requested change: narrow the bullet to workspace membership, billing, and settings, leave the cross-team claim solely in the VERIFY-marked paragraph on line 35, and apply the same narrowing to the Admin (workspace role) entry at.agents/references/terminology.md:153.src/content/docs/enterprise/team-management/workspaces.mdx:45— [IMPORTANT] "Only workspace admins can create a new team" directly contradictssrc/content/docs/enterprise/team-management/teams.mdx:120("Create a team" is ✓ for Member) andteams.mdx:27("The person who creates the team becomes the Team Owner"), neither of which this PR scoped even though it scoped the adjacent one-team-at-a-time and ownership claims on the same page. Requested change: add the same multi-team scoping to the "Creating a team" section and the "Create a team" permissions row onenterprise/team-management/teams.mdxso the two linked pages agree.src/content/docs/enterprise/team-management/workspaces.mdx:9-11— [SUGGESTION] The page opens with a disambiguation:::noteabout what a workspace is not, before any definition, violating the compression contract's "lead with a one-to-three-sentence user-facing summary" and AGENTS.md's guidance that callouts interrupt rather than open. Requested change: move the:::notebelow the availability paragraph so lines 13-16 lead the page.src/content/docs/enterprise/team-management/workspaces.mdx:81— [SUGGESTION] The "Workspace spend limits" section packs four rules (three independent cap levels, first-cap-wins precedence, each cap's blast radius, and per-role spend visibility) into one ~90-word paragraph, against AGENTS.md → Page length and scannability. Requested change: keep the first sentence as the lead and break the three cap levels and the visibility rule into bullets..agents/references/terminology.md:157— [NIT] The new "Team and workspace terms" section defines Private and Hidden but omits Open, whichworkspaces.mdx:41bolds alongside them as the third team visibility. Requested change: add an Open (team visibility) glossary entry matching the sibling entries' format (suggestion block provided).src/content/docs/enterprise/team-management/workspaces.mdx:86— [NIT] The Related pages bullet writes "Admin panel" in lowercase, but AGENTS.md → Core features treats "Admin Panel" as a proper feature name, and the same PR writes it correctly atteams.mdx:153and at line 70 of this file. Requested change: capitalize it to "Admin Panel" (suggestion block provided).
Verdict
Request changes
Narrow the workspace Admin bullet to workspace-scoped duties, scope team creation and the permissions table to the single-team model, lead the page with its summary, break the spend-limit rules into bullets, and complete the glossary and Admin Panel casing. Co-Authored-By: Warp <agent@warp.dev>
Add VERIFY markers for the one-workspace-per-user constraint, the four setting-resolution patterns, and the spend-cap precedence and visibility rules, each listed under Unverified claims in the PR body. Co-Authored-By: Warp <agent@warp.dev>
hongyi-chen
reviewed
Sep 10, 2026
Removes the ':::note' callout distinguishing the account-level workspace from the per-team Warp Drive workspace and Slack workspace, per reviewer feedback on PR #723.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this feature does
Workspaces let Enterprise accounts federate multiple teams under one company account, with a workspace-level admin role, billing, and settings that sit above each team's own configuration. This closes a docs gap for functionality already shipping in the client — workspace admin/owner badges, teamless-member team discovery, and multi-team invites — through
v0.2026.09.02.08.27.stable_01(2026-09-02).Summary
Adds a new "Workspaces" page documenting Warp's native (multi-team) workspace model for Enterprise accounts, and fixes the existing single-team docs that contradicted it. Based on
specs/multi-team-workspace-settings,specs/workspace-admin-roles,specs/team-crud,specs/team-joining-flows,specs/teamless-workspace-users, andspecs/workspace-spend-limitsinwarpdotdev/warp-server, the client model inapp/src/workspaces/workspace.rsandapp/src/settings_view/teams_page.rsinwarpdotdev/warp, and the public changelog entries for teamless team discovery (#15246) and workspace admin/owner badges (#15123).Originating thread: https://warpdev.slack.com/archives/C09BVK0PL3Y/p1788994285024009
Changes
New page —
src/content/docs/enterprise/team-management/workspaces.mdxCovers what a workspace is vs. a team, the three workspace roles (member/admin/owner), teams inside a workspace (creation, Open/Private/Hidden visibility), joining flows, the teamless state, how workspace settings interact with team settings, and workspace spend limits. Disambiguates the organizational workspace from the per-team Warp Drive workspace and from a Slack workspace.
Enterprise team-management pages — accuracy fixes and cross-links
teams.mdx- fixed the "one team at a time" note and the roles section to account for the workspace-level admin/owner role and multi-team membership.admin-panel.mdx- added cross-links to the new page's settings-interaction and spend-limit sections.roles-and-permissions.mdx- added a note that a workspace-level role sits above the team roles this page describes.Other accuracy fixes and cross-links
knowledge-and-collaboration/teams.mdx- dropped the unqualified "one team at a time" claim; scoped it to self-serve/Business plans, linked to the new page.knowledge-and-collaboration/admin-panel.mdx- noted that on a multi-team Enterprise account, many settings are configured once at the workspace level.enterprise/support-and-resources/billing.mdx- noted the optional workspace-level spend cap that sits above the team-level limits this page documents.Navigation and glossary
src/sidebar.ts- added "Workspaces" as the first entry under Enterprise > Team management..agents/references/terminology.md- added a "Team and workspace terms" section with a glossary entry for "workspace", disambiguating it from the Warp Drive workspace and a Slack workspace.Rework changes (cycle 1)
Addressed every review finding from this cycle on
workspaces.mdx:NATIVE_WORKSPACESis only enabled for Warp's internal plan tier. Reworded to "an Enterprise-plan capability, currently available to a limited set of accounts" and kept the existing VERIFY marker on rollout scope. Resolved.Separately, per direct requester feedback in the originating thread: did an editing pass over
workspaces.mdxto trim implementation-flavored explanation and tighten prose/tone, while keeping every VERIFY marker and the Unverified claims section intact.Rework changes (cycle 2)
Human-directed pass covering the three findings left open by the final review.
teams.mdx:148) - The cross-reference scoped the legacy Team Owner model to native multi-team workspaces. Rewrote it to scope Team Owner and ownership transfer to the single-team model, and to say that ownership sits at the workspace level on a multi-team workspace. Applied the same scoping to the note onroles-and-permissions.mdx, which carried the same defect, and added a short paragraph toworkspaces.mdxstating that a team inside a workspace has only member and admin roles (with a VERIFY marker, since only the internal spec confirms it). Resolved.workspaces.mdx:31,34,62) - Took the reviewer's marker option: added a VERIFY marker on the statement that a workspace admin has admin-level permissions on teams they don't belong to, dropped the duplicate assertion from the Admin role bullet, and narrowed the teamless-members sentence to workspace-level oversight instead of restating cross-team resource management. Both new markers are listed under Unverified claims. Resolved.terminology.md) - Added the sibling entries the reviewer named: Admin (workspace role), Delegated (setting pattern), and Combined (setting pattern). Resolved.The
Agent docs reviewcheck fails whenever the independent review's verdict isRequest changes- the workflow'sverify_review_signal.pystep fails on a blocking verdict. The findings behind each verdict on this branch are addressed here.Follow-up findings from the review pass on
c1afce9d:workspaces.mdx:31) - Narrowed the Admin role bullet to workspace membership, billing, and settings, leaving the cross-team authority claim only in the VERIFY-marked paragraph. Applied the same narrowing to the Admin glossary entry. Resolved.teams.mdx(workspaces.mdx:45) - Added the multi-team scoping to the "Creating a team" section and above the "Permissions overview" table onteams.mdx, so the "Create a team" row and the Team Owner sentence read as the single-team model. Resolved.workspaces.mdx:9-11) - Moved the disambiguation note below the definition and availability paragraphs so the page leads with its summary. Resolved.workspaces.mdx:81) - Kept the lead sentence and broke the three cap levels and the visibility rule into bullets. Resolved.workspaces.mdx:86) - Capitalized to Admin Panel. Resolved.Follow-up findings from the review pass on
86ec119c:Source files consultedpinning, caveat de-duplication acrossteams.mdx, the plan-vs-workspace-shape wording onknowledge-and-collaboration/teams.mdx, sidebar ordering, "Enterprise accounts" casing, and aTeamsentry in Related pages) are left for the human reviewer rather than guessed at.Note on the
Agent docs reviewcheck: its run against86ec119cfailed in the workflow's own Publish the independent review step withAn error occurred trying to start process '/usr/bin/bash' ... Argument list too long- the step passes the whole agent transcript through theAGENT_OUTPUTenvironment variable, which exceeded the exec argument limit. That failure is in.github/workflows/agent-docs-review.yml, not in this PR's diff, and it prevented the review from being published at all.Rework changes (cycle 3)
Human-directed follow-up: the requester left an inline comment "can we remove this note" anchored on the ':::note' callout distinguishing the organizational workspace from the per-team Warp Drive workspace and a Slack workspace.
workspaces.mdx:14-16) - Deleted the ':::note' callout entirely in 85fe20f. The disambiguation content is dropped rather than folded into prose, per the request. Resolved.Visual verification
Computer-use video recordings
Docs walkthrough: Workspaces, Teams, Roles & Permissions: Continuous scroll-through of the Workspaces page top to bottom, then the Teams page sections (Creating a team, Permissions overview, paragraph before Related resources), then the top of the Roles and permissions page.
Computer-use screenshots (6)
Top of the Workspaces docs page showing the H1 title "Workspaces", subtitle, the two intro body paragraphs, and the "Workspace vs. team" H2 heading directly following them with no note/callout box present.
The "Workspace roles" section of the Workspaces page, showing the three role bullets: Member, Admin, and Owner.
The "Workspace spend limits" section of the Workspaces page, showing intro paragraph and bulleted list: Workspace cap, Team cap, Per-user limit, Spend visibility.
The "Creating a team" section on the Teams page, showing the paragraph beginning "When creating a team" and the paragraph immediately after it about Enterprise accounts with multiple teams.
The "Permissions overview" heading on the Teams page with its sentence beneath, and the top of the permissions table showing Action/Owner/Admin/Member columns.
The paragraph immediately before "Related resources" on the Teams page, discussing the Team Owner role vs. workspace-level ownership on multi-team Enterprise accounts.
Captured against a local preview of
86ec119c, except the first screenshot (top of page) which was recaptured against the live Vercel preview of85fe20fto confirm the note callout removal. The earlier top-of-page capture from that pass is superseded and removed; the remaining five screenshots document sections untouched by cycle 3 and remain valid.Content design plan
Audience and JTBD: An IT admin or workspace admin at an Enterprise account on Warp's multi-team workspace model, who needs to understand how workspace roles, billing, and settings relate to the single-team model the existing docs describe.
Problem: The only existing docs describe a single-team model where the team is the sole management surface. Admins on a multi-team workspace see workspace-level roles, badges, and settings the docs never mention, and the existing team docs actively contradict what they see (for example, "each Warp user can only be an admin or member of one team at a time").
Goals:
Purpose and value: Without it, workspace admins have no accurate reference, and the existing team-management pages describe a model the product has moved past for multi-team Enterprise accounts.
Content type: Conceptual — the reader is learning a new organizational model, not performing a single task.
Skill and template:
draft_conceptual/.agents/templates/conceptual.mdHigh-impact scenarios:
Unverified claims
All nine markers below are in
src/content/docs/enterprise/team-management/workspaces.mdx. Source and what would confirm each:warp-server/billing/config/tiers/showsNATIVE_WORKSPACESenabled only for Warp's own internal enterprise plan (warp_plan.yaml); confirm the customer-facing rollout stage.specs/team-joining-flowsexplicitly defers join requests for Private teams.specs/team-joining-flows, not confirmed against the shipped client.specs/teamless-workspace-users/DISCUSSION.md, which frames several restrictions as intended fixes rather than confirmed-shipped; only the team-discovery UI is directly confirmed via changelog entry #15246.teams.mdxandroles-and-permissions.mdx.Documentation risk
Risk: engineering-review-required
Rationale: New feature page about the native workspaces model (multi-team enterprise orgs, roles, spend limits); contains open VERIFY markers on plan availability and specific rollout scope.
Docs override: none
Co-Authored-By: Warp agent@warp.dev