docs: document Warp's native workspaces model - #723
Open
warp-agent-staging[bot] wants to merge 11 commits into
Open
docs: document Warp's native workspaces model#723warp-agent-staging[bot] wants to merge 11 commits into
warp-agent-staging[bot] wants to merge 11 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.
tylerlam-warp
approved these changes
Sep 10, 2026
Co-authored-by: Tyler Gaw <1650449+tylergaw@users.noreply.github.com> Co-authored-by: Warpy <warpy@warp.dev>
Contributor
There was a problem hiding this comment.
Review summary
The independent agent completed its review for this commit.
Findings
- PR body
## Documentation risksection — [IMPORTANT] DeclaresRequested engineering reviewers: tylergawandEngineering review status: approved, but GitHub shows onlyhongyi-chenwas ever requested (comment only, no approval), the sole APPROVED review is from unrequestedtylerlam-warpon stale commit 17e516b (before the 47/-78 linedocs: revise workspaces after reviewrewrite that produced the current head). Requested resolution: correct the reviewer field, reset status topending, and re-request review on the current head. src/content/docs/enterprise/team-management/workspaces.mdx:51— [SUGGESTION] "Unassigned users cannot start cloud agent or factory runs until they join a team." isn't obviously covered by the three cited source files (all spend-limit UI, not run eligibility). Requested resolution: cite supporting source or add a VERIFY marker.src/content/docs/enterprise/team-management/workspaces.mdx:57— [SUGGESTION] "Model and agent settings remain team-level." isn't obviously supported by the cited sources. Requested resolution: confirm against source or add a VERIFY marker.src/content/docs/enterprise/team-management/workspaces.mdx:16— [NIT] style_lint flags bolded "Membership" as absent from terminology.md. Requested resolution: add a glossary entry or unbold.src/content/docs/enterprise/team-management/workspaces.mdx:45— [NIT] style_lint flags bolded "Team discovery" as absent from terminology.md. Requested resolution: add a glossary entry or unbold.
Verdict
Request changes
Contributor
Author
|
This PR was generated with Warp. Comment    |
warp-agent-staging
Bot
added
the
factory:docs-factory
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:35— [SUGGESTION] The 'Teams inside a workspace' section says workspace admins 'manage every team's membership and settings' but never states whether an individual team keeps its own delegated admin/owner (as Team Owner/Team Admin do for single-team workspaces per roles-and-permissions.mdx). Requested change: add a sentence clarifying whether team-level admin delegation still exists inside a multi-team workspace or whether workspace roles fully replace it.src/content/docs/enterprise/team-management/workspaces.mdx:26— [SUGGESTION] The PR's own validation artifacts include a screenshot of the 'Workspace admin'/'Workspace owner' badges in a team member list, but the page embeds no screenshot. Requested change: embed that captured screenshot near this sentence to give readers a concrete visual reference for the badge-based role model.src/content/docs/enterprise/support-and-resources/billing.mdx:79— [NIT] 'a workspace-level cap above their team limits' is ambiguous (could mean 'higher than' or 'in addition to'). Requested change: reword to 'a workspace-level cap in addition to their team limits'.
Verdict
Approve with nits
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
2 participants
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 feature does this document?
Workspaces for Enterprise accounts that manage multiple teams.
Summary
Content design plan
Validation
npm run build— passed after applying the repository'spatch-packagepostinstall; generated 386 Markdown docs and indexed 388 HTML files.npm run typecheck— passed with 0 errors and 7 repository-level hints.style_lint.py --changed— scanned 8 files and reported 67 existing/file-level warnings: 1 consecutive callout, 3 callout-density, 4 screenshot-width, 1 tone, and 58 glossary warnings. The two revised pages account for 7 glossary-only warnings.Unverified claims
Documentation risk
Risk: engineering-review-required
Rationale: Documents Enterprise workspace behavior, roles, invitations, settings, SSO, and billing semantics.
Source files consulted: workspace AI controls, workspace settings UI strings, workspace spending limits, workspace membership logic, workspace invite links, workspace email invites, domain capture, cloud-run team eligibility, factory active-team selection
Requested engineering reviewers: tylerlam-warp
Engineering review status: pending
Docs override: none
Review provenance:
tylerlam-warpapproved commit17e516band supplied corrections incorporated in later commits. The current head has not been approved.Computer-use screenshots (10)
Workspace roles section listing Member, Admin, and Owner roles with descriptions, and the "Teams inside a workspace" section describing team visibility options (Open and Hidden).
Bottom portion of the page showing full "Workspace settings and team settings" section, "Workspace spend limits" section, and "Related pages" list with 5 linked resources (Team management, Admin Panel, Roles and permissions, Single Sign-On, Enterprise billing), plus Previous/Next page navigation footer.
Top of the Workspaces documentation page showing the page title, breadcrumb, opening paragraph, sidebar with Workspaces highlighted under Team Management, and the Workspaces and teams section with Workspace level/Team level/Membership bullets.
Workspace roles section (Member, Admin, Owner) and Teams inside a workspace section describing Open and Hidden team visibility options.
Bottom portion of the page showing Workspace settings and team settings, Workspace spend limits, and Related pages sections with navigation links to Previous (Trust Center) and Next (Teams).
Top of Workspaces page showing title, breadcrumb, opening paragraph, sidebar navigation, and the "Workspaces and teams" section with workspace/team/membership bullets
Workspace roles section (Member, Admin, Owner) and complete Teams inside a workspace section showing Open/Hidden visibility options
Unassigned users (final part), Workspace settings and team settings, Workspace spend limits, and Related pages list at the bottom of the page
Workspaces docs page showing the complete "Workspace settings and team settings" section, including the heading, both paragraphs, and the subsequent "Workspace spend limits" section.
SSO docs page showing the opening paragraph (workspace-level SSO configuration) and the complete "SSO enforcement and session management" section listing SSO enforcement, MFA, and session management at the workspace/admin level.