[yvjnlee]

Summary

Factory permissions let Enterprise teams separate people who run work from people who configure factories. This draft documents role capabilities, inherited Admin access, defaults, and team-wide and per-factory assignments.

Launch preparation for Thursday, October 29, 2026, per the requester. Do not merge until production availability is confirmed. The requester approved preparing this draft before release; this is not a claim that permissions have shipped.

Adds /factories/permissions/ to Factory configuration. Replaces the security page's short role table with a link so the capability and inheritance rules have one home.

Related issues

User-requested documentation for the Factory Permissions launch. No separate docs issue.

Validation

• npm run typecheck
• npm run test:heading-vars
• npm run build
• npm run test:heading-tocs
• npm run test:homepage-json-ld
• Repository internal-link, style, compression, and PR-body checks.
• Rendered HTML confirms the title, both tables, procedure anchors, and UI labels.
• Trunk is not installed locally. No computer-use verification or screenshots.

The checks pass. Style lint reports warnings for exact UI labels and three pre-existing glossary terms on the security page; no style errors.

Screenshots

None. This changes documentation and navigation only.

Follow-ups

• Confirm the production rollout before merging; availability remains unverified.
• Check the assignment instructions against the released UI.

The draft omits definition-change proposals, force-merging, and clearing overrides back to inheritance. Those workflows need separate launch verification. Workspace-default navigation is also out of scope; the draft documents precedence without inventing a settings path.

Content design plan

Audience and JTBD: An Enterprise team or workspace admin choosing who can run factories and who can change their configuration.

Problem: The existing security page names roles but does not explain assignment, defaults, or how team roles differ from per-factory overrides.

Goals:

• Choose User or Editor without granting team administration.
• Assign a team-wide role or a per-factory exception.
• Understand default changes and factory-creation access.

Purpose and value: Permissions need a task-focused page with procedures. The security page is already near its length budget; it retains a summary and links to this canonical page.

Content type: Combined feature documentation, with capability and precedence tables before assignment procedures.

Skill and template: draft_feature_doc / .agents/templates/feature-doc.md.

High-impact scenarios:

• Covers: Enterprise eligibility, inherited Admin, team roles, factory overrides, defaults, factory creation, and external access boundaries.
• Excludes: API administration, billing setup, definition-change review, and provider credential setup.

Unverified claims

• Production availability is pending. The source review confirms implemented behavior, not release. Recheck deployment before merge.
• Assignment controls are verified against development source, not a live released build. Confirm the labels and team-access destination at launch.

Documentation risk

Risk: engineering-review-required
Rationale: Documents permissions, eligibility, defaults, and assignment procedures for an explicitly requested launch-preparation draft. Availability is a pre-merge check.
Source files consulted: warp-server/authz/agent_platform_policies.go@22e10c4, warp-server/model/types/factory_user_roles.go@22e10c4
Engineering review status: pending
Docs override: none

Source-owner resolution found no single owner, so no reviewer is requested.

UI verification uses the same source revision: factory Access, the Users page, and its ChangeSeatTypeModal. No live released UI was tested.

Agent context

Conversation

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

[vercel]

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

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 28, 2026 7:11pm UTC

[rachaelrenk]

Could we shorten the sidebar label to “Factory permissions,”? Keeping the topic first makes the navigation easier to scan. The article titles can retain “Managing…”

Suggested change

	{ slug: 'factories/permissions', label: 'Managing factory permissions' },
	{ slug: 'factories/permissions', label: 'Factory permissions' },

[rachaelrenk]

Is “User” used anywhere in the customer-facing product, or is the role always called “Factory user”? If “Factory user” is the label customers see, let’s use that consistently instead of introducing “User access” and then explaining the naming difference. If I'm understanding correctly, I'd suggest updating this intro paragraph to something like:

Suggested change

	Give teammates User access to run work without changing the factory, or Editor access to configure its agents, repositories, and automations. The User role appears as **Factory user** in dropdowns.
	> Give teammates **Factory user** access to run work without changing the factory, or **Editor** access to configure its agents, repositories, and automations.

and then revise "User" to "Factory user" throughout the rest of the doc?

[rachaelrenk]

Suggested tweak for clarity:

Suggested change

	Role management requires an Enterprise plan. On other plans, team members have Editor access.
	Assigning User and Editor roles requires an Enterprise plan. On all other plans, team members have Editor access.

[rachaelrenk]

Suggested edit for clarity as "override" isn't defined until later in the doc.

Suggested change

	Factory creation uses your team-level role. An Editor override for one factory doesn't grant permission to create factories.
	Permission to create factories depends on your team-wide factory role. Assigning someone Editor access to an individual factory does not let them create new factories.

[rachaelrenk]

Could we explain team-wide roles and factory-specific assignments before discussing these restrictions? “Override” appears twice before it’s defined. We could also use “a role assigned for one factory” rather than introducing a separate term.

Possible, more plain-language explanation:

Suggested change

	Team and workspace admins and owners inherit Admin access from their [team or workspace role](https://docs.warp.dev/enterprise/team-management/roles-and-permissions/). You can't assign Admin in a factory's role settings or reduce an admin's access with a User override.
	Team and workspace admins and owners inherit Admin access from their [team or workspace role](https://docs.warp.dev/enterprise/team-management/roles-and-permissions/). You can’t grant or reduce that access through a factory’s role settings.

[rachaelrenk]

Suggested edit to give some concrete examples:

Suggested change

	Editors can attach resources already connected to the team. Connecting team-wide integrations and managing shared runners require separate team or workspace permissions.
	Editors can attach existing team secrets, MCP servers, and integrations to a factory. Connecting new team-wide integrations and managing shared runners require separate team or workspace permissions.

[rachaelrenk]

Maybe a little more specific, like:

Suggested change

	## How roles apply
	## Team-wide roles and factory-specific access

[rachaelrenk]

Suggested change

	A team-level role applies across the team's factories. Override that role for one factory to give a teammate different access there.
	A team-wide factory role applies to every factory on the team. To override that role for an individual factory, assign the person a different role in that factory’s access settings.

[rachaelrenk]

Suggested change

	You must be a team or workspace admin to assign User and Editor roles.
	You can change team-level roles directly in your team's [Admin Panel](https://docs.warp.dev/enterprise/team-management/admin-panel/). The **Manage team access** link in factory settings opens the same member list.
	You must be a team or workspace admin to change team-wide factory roles. Open your team’s [Admin Panel](https://docs.warp.dev/enterprise/team-management/admin-panel/) to change roles directly, or follow the steps below to change roles from your factory settings.

[rachaelrenk]

To make this more consistent with other procedures in the docs:

Suggested change

	1. In the <a href={VARS.FACTORY_WEB_APP_URL}>{VARS.FACTORY_WEB_APP}</a>, open a factory and click **Settings**.
	1. In the <a href={VARS.FACTORY_WEB_APP_URL}>{VARS.FACTORY_WEB_APP}</a> sidebar, expand the factory and click **Settings**.

[rachaelrenk]

Suggested change

	2. In the factory settings sidebar, click **Access**, then **Manage team access**.
	2. Under **Settings**, click **Access**, then click **Manage team access**.

[rachaelrenk]

Suggested change

	1. In the web app, open that factory and click **Settings**.
	1. In the <a href={VARS.FACTORY_WEB_APP_URL}>{VARS.FACTORY_WEB_APP}</a> sidebar, expand the factory and click **Settings**.

[rachaelrenk]

Suggested change

	2. In the factory settings sidebar, click **Access**.
	2. Under **Settings**, click **Access**.

[rachaelrenk]

Suggested change

	Factory roles don't grant access to repositories or external services. Runs use the configured [repository identity](/factories/factory-as-code/#credentialstrategy), [secrets](/factories/secrets/), and [MCP servers](/factories/factory-as-code/).
	Factory roles don’t grant access to repositories or external services. A run’s access to those resources depends on its configured [repository identity](/factories/factory-as-code/#credentialstrategy), [secrets](/factories/secrets/), and [MCP servers](/factories/factory-as-code/).

[rachaelrenk]

Suggested change

	Specification approval follows the foreman's instructions. Your repository's permissions and branch protection control who can approve and merge pull requests. See [Human decision points and permissions](/factories/factory-agents/#human-decision-points-and-permissions).
	Additionally, factory roles also don’t determine who can approve specifications or merge pull requests. Specification approval follows the foreman’s instructions, while your repository’s permissions and branch protection rules govern pull request approval and merging. See [Human decision points and permissions](/factories/factory-agents/#human-decision-points-and-permissions).

[rachaelrenk]

👋 Approving this PR to unblock, but I left some suggested edits with tweaks to wording for clarity and flow. Please take a look and implement feedback where it makes sense.

[rachaelrenk]

Note on these procedures: I can’t verify the flows in production as the factory Settings has no settings sidebar, Access item, or Manage team access link in my current view. I'm guessing this could be pending rollout or dependent on my admin permissions? Just wanted to call out that we should verify both procedures against the released UI before merge.

[yvjnlee]

Yup they're are all on staging and sent a screenshot to you on slack with an example of what it currently looks like, will address all the comments above as well, thanks for the review!