Skip to content

docs: clarify teams, workspaces, and administration roles - #1067

Open
rachaelrenk wants to merge 14 commits into
mainfrom
rrenk/teams-workspaces-roles
Open

rachaelrenk wants to merge 14 commits into
mainfrom
rrenk/teams-workspaces-roles

Conversation

@rachaelrenk

@rachaelrenk rachaelrenk commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

What this feature does

Teams share factories and other resources, while roles determine who can administer them. This documentation change standardizes terms and gives self-serve customers team-first guidance and distinguishes Enterprise workspace administration from team and factory access. It documents existing behavior, not a new product release.

Summary

PR 1 of the teams, workspaces, and factory-access reconciliation. Standardizes team and Enterprise workspace definitions, consolidates administration guidance, and distinguishes membership, administrative roles, factory permissions, and plan conditions.

The membership guide lives under Terminal at /knowledge-and-collaboration/teams/, with Factories and Enterprise sidebar shortcuts to the same page. The canonical-source map highlights six core topics rather than every related reference. Spending rules now live in Enterprise billing, with authority explained on Workspaces.

Provider-specific setup handoffs remain in the separate stacked PR #1071. Moving procedures out of Pricing FAQs is recorded as separate follow-up work.

Changes

  • Teams and workspaces - Standardize definitions and terminology. Keep the membership guide under Terminal, provide Factories and Enterprise shortcuts, and document browser invitations, joining, and conditional first-team setup.
  • Roles - Clarify ownership, additional admins, and the boundaries between team, workspace, and factory access. Document role checks, promotion, and ownership transfer.
  • Admin Panel - Consolidate settings guidance, explain plan restrictions and workspace enforcement, and remove the extra administration shortcut from the Factories sidebar.
  • Plans and billing - Distinguish usage visibility, purchases, spending limits, and payment management. Make Enterprise billing the owner of cap types and limit rules; keep admin authority on Workspaces.
  • Privacy - Clarify browser privacy preferences and account-deletion prerequisites. Keep service-improvement collection, provider retention, and stored run data distinct.
  • Content ownership - Replace the broad page inventory with six core canonical sources.
  • Compatibility - Update links and redirects, preserve legacy anchors, and repair the deletion-policy audit reference with a regression test.

Canonical content ownership

These pages own the definitions and rules for teams, workspaces, roles, settings, and plans. Other pages provide the context needed for their task and link here for details.

Topic Canonical page and tabs What belongs there
Teams and membership Managing team membership
Primary tab: Terminal; shortcuts: Factories, Enterprise
Team definition; creating teams; inviting, joining, removing members, leaving, and deleting teams
Team roles Roles and permissions
Tabs: Terminal, Enterprise
Owner, admin, and member responsibilities; additional-admin availability; role changes and ownership transfer
Workspaces and workspace roles Workspaces for Enterprise teams
Tabs: Enterprise
Workspace definition; workspace roles and membership; administration across teams; workspace policies
Factory permissions Managing factory permissions
Tabs: Factories
Who can run or configure factories; role defaults, individual assignments, and inherited admin access
Team and workspace settings Admin Panel
Tabs: Terminal, Enterprise
Where to find shared settings; which settings are editable; how workspace policies affect teams
Plans Plans, pricing, and refunds
Tabs: Support
Terminal versus factory plans; plan choices; included allowances and funding requirements

Billing, integration, and privacy pages remain the owners of their detailed rules; they are supporting references rather than core topics in this map. Current commercial prices remain on Warp pricing.

Plans and administration

Standard capabilities below summarize the owning references; account-specific access can differ. Current prices and commercial terms remain on the pricing and billing surfaces, not in a new purchase table.

Product and plan Administrative scope Human and factory roles Usage and controls
Warp Factories: Start One self-serve team One owner; no additional admins in the standard plan. Owner inherits factory Admin; non-admins have Editor access. Factory runs use shared funding, not a member's personal allowance.
Warp Factories: Scale One self-serve team One owner; owner and admins can add admins. Those admins inherit factory Admin; non-admins have Editor access. Flat team subscription with shared included usage. Admins see per-user team totals with unlimited history; non-admins see their own usage. Shared data controls remain subject to plan-fixed values.
Warp Factories: Enterprise One workspace containing teams One workspace owner; workspace admins administer every team. Team admins administer their team. Factory user/Editor assignment is included in the standard plan. Contract-based funding; workspace/team/member spending controls, detailed reporting, and supported Enterprise data controls.
Warp Terminal and local agents: Free Self-serve team No additional admins in the standard plan. Do not infer factory-plan entitlements from a Terminal plan name.
Warp Terminal and local agents: Build, Max, Business Self-serve team Additional admins supported. Paid per-seat subscriptions are distinct from the Scale team-funding model.
Warp Terminal and local agents: Enterprise Workspace and team administration Separate workspace and team roles. Funding and available controls follow the contract and applicable policies.

Roles and scope

Role Scope Responsibilities Important boundary
Team owner Self-serve team Team administration and ownership transfer Exactly one owner; plan restrictions still apply. Adding an admin does not transfer ownership.
Team admin One team Membership, configurable settings, supported admin promotion, and available team/member spending limits Not automatically an Enterprise workspace admin; cannot transfer ownership.
Team member One team Shared resources within policies Membership is not administration or a read-only promise; factory access is separate.
Workspace owner Enterprise workspace Workspace administration and ownership transfer Exactly one owner.
Workspace admin Enterprise workspace and its teams Workspace membership/settings, supported billing controls, and administration across every team Does not replace the owner or automatically gain access to personally owned runs.
Workspace member Enterprise workspace Access through their team memberships and roles Not automatically a member of every team; can separately administer a particular team.
Factory user Team-wide factory assignment or one factory View a factory and run work Does not directly configure the factory.
Editor Team-wide factory assignment or one factory Factory configuration and attaching existing resources Does not itself grant shared-integration installation or team administration. A one-factory assignment does not grant factory creation.
Inherited factory Admin Applicable team or workspace Factory administration within the inherited scope Not independently assigned alongside Factory user and Editor; factory-role assignments cannot reduce it.

Self-serve team/workspace roles mirror one-to-one; customers manage team roles rather than an independent workspace-role selection. Workspace-role terminology remains Enterprise-facing, except where a literal UI label or a real permission/billing/policy scope needs explanation.

Billing visibility is not one permission: on Scale, non-admins can see their own usage. Eligible active members can purchase shared usage without thereby gaining subscription or payment-management authority. This PR does not infer a general right to view payment-card details from either action.

Content design plan

  • Team membership: A self-serve or Enterprise customer adding colleagues needs one membership guide, not conflicting general and Enterprise versions. Consolidate the existing combined page, keep task-local billing consequences, and link roles and Enterprise organization details to their owners.
  • Roles: A customer identifying who can administer a team or factory needs scoped definitions and plan conditions. Rehome the existing combined reference/procedure page; detailed integration matrices remain out of scope.
  • Admin Panel: An admin finding a browser setting needs one settings reference with enforcement and plan restrictions. Consolidate the existing pages, preserve privacy/model guidance and compatibility anchors, and link billing and role details rather than duplicate them.
  • Related corrections: Keep the existing privacy page canonical for personal preferences and product storage; correct its ownership-transfer prerequisite. Enterprise billing owns spending-cap types and limit interactions; Workspaces explains admin authority and links to those rules.

Editorial verdict: Retain the existing customer tasks while removing competing policy owners. Preserve browser-only administration, ownership-transfer consequences, settings enforcement, and the distinction between provider retention, service-improvement collection, and saved run data. Cross-links supply discovery without creating another documentation space. No new feature, compliance commitment, or provider lifecycle guarantee is introduced.

Validation

  • Merged current main before final validation.
  • npm run typecheck: 0 errors, 7 hints.
  • npm run test:heading-vars: 5 passed.
  • npm run build: 426 pages.
  • npm run test:heading-tocs: 3,686 entries validated.
  • npm run test:homepage-json-ld: passed.
  • Migration regression check: all 88 legacy anchors retained across the five former source pages; all six HTML/Markdown redirects verified.
  • Latest whole-tree internal-link scan: 425 Markdown files, 5,308 links, 0 broken.
  • Initial external/changed-page audit, before the usability follow-up: 33 pages, 681 internal link occurrences and 75 external occurrences covering 38 unique external URLs; no broken links. Same-site documentation URLs were resolved against the proposed local tree, not the pre-merge deployment.
  • Core page budgets: team membership 1,198 words, roles 1,401, Admin Panel 1,474; all pass.
  • Terminology lint regressions: 7 context-aware and 27 factory proper-noun cases passed.
  • Final style lint: no errors; 20 warnings across the three core pages, 270 across 36 changed public pages, including inherited findings on the broader touched pages. No automatic terminology replacement was applied.
  • Missing-docs audit tests: 35 passed. Reviewer-routing tests: 19 passed. The stale retired-Teams seed reference that caused CI failure is corrected without weakening the surviving regression rule.
  • git diff --check: passed; working tree clean.

Trunk is unavailable locally. Node 25 is outside the package's declared engine range; the checks above completed. Existing build warnings include chunk size, deprecated Markdown configuration, missing/empty i18n data, and the /404 route conflict.

Usability validation

The original deployed-preview walkthrough asked 28 JTBD-based questions. After these fixes, a focused retest followed real homepage/sidebar/article links through newly rendered local HTML for the affected tasks; the internal content map and backend source were not navigation shortcuts.

Questions Retest result
Q2–Q3: Create/join a team and invite colleagues without the Warp app Clear for the documented conditional first-team onboarding and existing-team browser flows; email/link invitations, joining, and blocked-account recovery are explicit.
Q4: Will adding a member change the bill? Product-specific consequences appear before inviting, with the right Terminal, factory, or Enterprise destination.
Q8: Transfer ownership and understand lost access Browser procedure and role-column alternative are present. Access-loss consequences precede confirmation; the new owner verifies afterward instead of sending the former owner back to an inaccessible panel.
Q23: What usage can members/admins see? Directly answered under Tracking usage and linked from factory billing.
Q24: Purchase usage versus change payment/subscription details Portal restrictions now precede the procedure; member purchases remain a separate permission.
Q25: Edit a purchase cap in a browser Billing → Additional usage/Add-on credits → Edit limit → Save, with a displayed-value check, missing-control fallback, and a separate Enterprise usage-cap link.
Q29: Identify my role or find an admin Selected-team badge instructions distinguish general admin access from exact ownership; members get an inviter/admin/support handoff, not an invented admin directory.

These are text/link usability results, not live-account authorization or provider-consent tests. The deployed preview was stale during the focused walkthrough; a later freshness check confirmed the new membership and role guidance is now served. Visual layout, search-dialog, responsive, accessibility-interaction, and product-account testing remain unperformed.

The provider questions Q13–Q16 were separately retested in PR #1071. Its Azure eligibility question remains an explicit owner-review limitation. The Docs usability validation toolkit has a separate handoff plan and is not implemented in either content PR.

Unverified claims

The first two items apply to src/content/docs/knowledge-and-collaboration/roles-and-permissions.mdx.

  • Standard factory-plan roles confirmed by Jason. Confirm legacy Terminal subscriptions and customer-facing treatment of account-specific entitlements before merge.
    Section: “Managing admins.” No production cohort inventory was performed.
  • Exercise both the member-menu and editable-role-column paths in the production Admin Panel before merge, including demotion and confirmation behavior.
    Section: “Promoting or demoting admins.” Both paths were inspected in source, not exercised live.
  • confirm what team admins see when a workspace limit blocks usage before documenting that notice
    Location: src/content/docs/enterprise/support-and-resources/billing.mdx, “Workspace spending limits.” The factory UI notice was inspected in source, not observed in a live account.
  • Confirm the launch setup flow and Blueprint preview against the live product; replace the removed agent-selection screenshot with current setup proof before publication.
    Location: src/content/docs/factories/quickstart.mdx. This marker is inherited from merged main; this PR only retargets the administration link on that page.
  • The personal browser privacy preference and its human-versus-service-account scope were traced through the client and server, but were not tested against a live account. No absolute collection guarantee or service-account opt-out is claimed.
  • The added browser onboarding, invitations, role badge, ownership transfer, and purchase-cap procedures were verified against source and rendered docs, not exercised in a logged-in product account.
  • The deployed application revision, effective runtime configuration, customer-specific entitlements, and visual rendering in a live product account were not independently verified. Existing tests were inspected for product behavior; only the documentation and lint checks listed above were executed.

Documentation risk

Risk: engineering-review-required
Rationale: Consolidates substantive role, plan, billing, administration, and privacy guidance; source checks and maintainer-provided SME confirmation do not replace the listed live-account checks.
Source files consulted: Existing Teams, Admin Panel, roles, factory permissions, privacy, and billing documentation; private implementation references and reviewer evidence are retained in the internal plan, not copied into this public PR.
Requested engineering reviewers: none
Engineering review status: pending
Docs override: none

No single owning engineer resolved for this cross-cutting change, so no reviewer is automatically requested.

Related issues

No issue number supplied. This follows the maintainer-led teams, workspaces, and factory-access review.

Follow-ups

  • Move subscription and payment-management procedures out of Pricing FAQs into task-based billing documentation. Keep FAQ answers concise and link to the procedures. This is separate follow-up work, not part of this PR.
  • Resolve the listed verification items before merge.
  • Review stacked PR docs: clarify factory integration setup prerequisites #1071 for provider setup prerequisites and handoffs; retain its explicit Azure/Jira policy limits before making broader reconnect/removal or eligibility guarantees.
  • Keep customer-specific terms, provider-side approvals, and commercial migration questions with their owners rather than infer them from role names.

Agent artifacts

Co-Authored-By: Warp agent@warp.dev

rachaelrenk and others added 2 commits November 19, 2026 11:41
Unify team membership, roles, and Admin Panel guidance; preserve Enterprise workspace scope and plan-qualified factory access.

Co-Authored-By: Warp <agent@warp.dev>
Preserve upstream factory worker and Blueprint guidance while retaining canonical administration links.

Co-Authored-By: Warp <agent@warp.dev>
@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
docs Ready Ready Preview Nov 20, 2026 5:24pm UTC

Request Review

@cla-bot cla-bot Bot added the cla-signed label Nov 19, 2026
@rachaelrenk rachaelrenk added warpy-factory Opened by the Warp factory agents and removed cla-signed labels Nov 19, 2026
@rachaelrenk

Copy link
Copy Markdown
Contributor Author

Terminology review record

  • reviewed_at: 2026-11-19 (UTC)
  • docs_head: 33531150
  • source_revisions: Maintainer-supplied terminology and role review dated November 19; implementation snapshots from November 18 development and the November 17 release, plus current native-app source. Private immutable references and reviewer evidence remain in the linked internal plan rather than being copied into this public record. Source inspection does not establish the deployed build.
  • terms_reviewed: Admin Panel; team; self-serve; team owner, admin, and member; workspace owner, admin, and member; Factory user; Editor; inherited factory Admin. No verified prior complete review record was available for this bounded scope; this is not a whole-glossary review.
  • outcome: proposed
  • human input: The maintainer supplied HYC/Isaiah confirmation of team-first self-serve naming, single ownership, and one-to-one role mirroring; Jason confirmed standard factory-plan roles; Eugene confirmed factory-role definitions. This records input to the proposal, not approval of the current PR head.
  • open_questions: The general naming/mirroring/ownership convention is confirmed. Actual entitlement cohorts, production UI flows, and the action-specific privacy/billing/integration follow-ups remain qualified in the PR body and owning references.
  • proposal_pr: docs: clarify teams, workspaces, and administration roles #1067

Detailed provider-specific permissions and lifecycle procedures remain in PR 2. No product settings were changed during verification.

rachaelrenk and others added 2 commits November 19, 2026 14:36
Add verified browser routes, clarify reporting visibility and billing prerequisites, and fix product-specific invitation handoffs.

Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Keep the existing deletion-policy regression on its canonical membership page and remove references to the retired duplicate.

Co-Authored-By: Warp <agent@warp.dev>
Relocate the canonical page to /factories/teams/, preserve cross-topic navigation, update internal references, and redirect legacy URLs directly.

Co-Authored-By: Warp <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
Align workspace descriptions across membership, administration, and billing documentation while keeping SSO details with settings guidance.

Co-Authored-By: Warp <agent@warp.dev>
Keep cap types and limit interactions in Enterprise billing; retain workspace administration guidance, links, and the legacy anchor.

Co-Authored-By: Warp <agent@warp.dev>
Apply review edits to role and Admin Panel descriptions, keep factory-role eligibility local, and distinguish Warp Terminal plans from Warp Factories plans while preserving heading anchors.

Co-Authored-By: Warp <agent@warp.dev>
Keep Factories and Enterprise sidebar shortcuts, redirect the former Factories URL, and preserve the refined content and legacy anchors.

Co-Authored-By: Warp <agent@warp.dev>

This branch was successfully deployed

1 active deployment
Preview — 4fffe835 Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cla-signed warpy-factory Opened by the Warp factory agents

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant