improvement(perm-groups): allow workspace filter for permission groups

Author: icecrasher321

apps/docs/content/docs/en/platform/enterprise/access-control.mdx

@@ -7,15 +7,22 @@ import { Callout } from 'fumadocs-ui/components/callout'
 import { FAQ } from '@/components/ui/faq'
 import { Image } from '@/components/ui/image'
 
-Access Control lets organization admins define permission groups that restrict what each set of organization members can do — which AI model providers they can use, which workflow blocks they can place, and which platform features are visible to them. Permission groups are scoped to the **organization** and apply to every workspace under it: a user belongs to at most one group per organization. Restrictions are enforced both in the workflow executor and in Mothership, based on the organization that owns the workflow's workspace.
+Access Control lets organization admins define permission groups that restrict what each set of organization members can do — which AI model providers they can use, which workflow blocks they can place, and which platform features are visible to them. Permission groups are scoped to the **organization** and can govern either every workspace in the organization or a specific subset of workspaces. A user can belong to multiple groups, but is governed by exactly one group in any given workspace. Restrictions are enforced both in the workflow executor and in Mothership, based on the organization that owns the workflow's workspace.
 
 ---
 
 ## How it works
 
-Access control is built around **permission groups**. Each group belongs to a specific organization and has a name, an optional description, and a configuration that defines what its members can and cannot do. A user can belong to at most one permission group **per organization**, and that group governs them in every workspace under the organization. Personal workspaces that do not belong to an organization have no permission groups.
+Access control is built around **permission groups**. Each group belongs to a specific organization and has a name, an optional description, a **workspace scope** (all workspaces or a specific subset), and a configuration that defines what its members can and cannot do. A user can belong to multiple permission groups, but at most one group governs them in any given workspace. Personal workspaces that do not belong to an organization have no permission groups.
 
-Sim resolves the governing group deterministically, with no per-workspace fallbacks: a user's explicitly assigned group takes precedence; otherwise the organization's **default group** applies (if one is set); otherwise no restrictions apply.
+Sim resolves the governing group for a user in a workspace deterministically, with **specific-over-all precedence**:
+
+1. a group the user belongs to that **specifically targets that workspace** takes precedence; otherwise
+2. a group they belong to that applies to **all workspaces** applies; otherwise
+3. the organization's **default group** applies (if one is set); otherwise
+4. no restrictions apply.
+
+Because a user's specific-scope groups may not overlap on a workspace, and a user may belong to at most one all-workspaces group, the governing group is always unambiguous.
 
 When a user runs a workflow or uses Mothership, Sim reads the resolved group's configuration and applies it:
 
@@ -34,7 +41,7 @@ Go to **Settings → Enterprise → Access Control** from any workspace in your
 
 ### 2. Create a permission group
 
-Click **+ Create** and enter a name (required) and optional description. You can also mark the group as the **organization default group** — when set, it governs every organization member who is not explicitly assigned to another group, as well as external workspace members operating in the organization's workspaces. Only one group per organization can be the default at a time.
+Click **+ Create** and enter a name (required) and optional description. Choose whether the group applies to **all workspaces** in the organization or only a **specific set** of workspaces — when specific, pick the workspaces from the multi-select. You can also mark the group as the **organization default group** — when set, it governs every organization member who is not explicitly assigned to another group, as well as external workspace members operating in the organization's workspaces. Only one group per organization can be the default at a time, and the default group always applies to all workspaces.
 
 ### 3. Configure permissions
 
@@ -130,7 +137,9 @@ Controls visibility of platform features and modules.
 
 ### 4. Add members
 
-Open the group's **Details** view and add members by searching for users by name or email. The member picker lists your organization's members. A user can belong to at most one group per organization — adding a user to a new group removes them from their current group.
+Open the group's **Details** view and add members by searching for users by name or email. The member picker lists your organization's members. A user can belong to multiple groups, but only one group can govern them in any given workspace — so adding a user to a group is rejected when it would conflict with another of their groups on a workspace (two all-workspaces groups, or two specific groups that share a workspace). In bulk adds, conflicting users are skipped rather than added.
+
+You can also change a group's workspace scope at any time from the **Workspaces** row in the Details view.
 
 External workspace members (people who have access to a workspace but belong to a different organization) are not assigned to groups individually. They are governed by the organization's **default group** when one is set; otherwise no restrictions apply to them.
 
@@ -159,10 +168,11 @@ When a user opens Mothership, their permission group is read before any block or
 
 ## User membership rules
 
-- A user can belong to **at most one** permission group **per organization**, and that group governs them in every workspace under the organization.
-- Moving a user to a new group automatically removes them from their previous group.
-- Users not assigned to any group fall under the organization's **default group** if one is set; otherwise no restrictions are applied to them.
-- Only one group per organization can be marked as the **default group**. The default also governs external workspace members operating in the organization's workspaces.
+- A user can belong to **multiple** permission groups, but **at most one** group governs them in any given workspace.
+- For a given workspace, a group that **specifically targets that workspace** takes precedence over a group that applies to **all workspaces**, which takes precedence over the organization's **default group**.
+- A user's specific-scope groups may not overlap on a workspace, and a user may belong to at most one all-workspaces group. Adding a user in a way that would violate this is rejected (single add) or skipped (bulk add) — memberships are never silently moved between groups.
+- Users not governed by any group fall under the organization's **default group** if one is set; otherwise no restrictions are applied to them.
+- Only one group per organization can be marked as the **default group**, and it always applies to all workspaces. The default also governs external workspace members operating in the organization's workspaces.
 - Personal or grandfathered workspaces that do not belong to an organization have no permission groups.
 
 ---
@@ -178,7 +188,11 @@ When a user opens Mothership, their permission group is read before any block or
   },
   {
     question: "Can a user be in multiple permission groups?",
-    answer: "A user can belong to at most one permission group per organization, and that group governs them across every workspace under the organization. Adding a user to a new group automatically removes them from their previous group."
+    answer: "Yes. A user can belong to multiple permission groups, but only one group governs them in any given workspace. A group that specifically targets a workspace takes precedence over an all-workspaces group, which takes precedence over the organization's default group. A user's specific-scope groups may not overlap on a workspace, and a user may belong to at most one all-workspaces group."
+  },
+  {
+    question: "Can a permission group apply to only some workspaces?",
+    answer: "Yes. When creating or editing a group, choose 'Specific workspaces' and select the workspaces it should govern. A specific-scope group governs its members only in those workspaces; elsewhere those members fall back to their all-workspaces group (if any) or the organization default. The default group always applies to all workspaces."
   },
   {
     question: "What governs a user who has no permission group assigned?",
@@ -189,8 +203,8 @@ When a user opens Mothership, their permission group is read before any block or
     answer: "Yes. Mothership reads the user's permission group for the workspace's organization before suggesting blocks or tools. Disallowed blocks are filtered out of the block picker, and disallowed tool types are skipped during workflow generation."
   },
   {
-    question: "Can I apply different restrictions to different people?",
-    answer: "Permission groups apply across the entire organization, so assign different sets of users to different permission groups to give them different restrictions. Who can access a given workspace is still controlled separately by workspace invitations and permissions."
+    question: "Can I apply different restrictions to different people or workspaces?",
+    answer: "Yes. Assign different sets of users to different permission groups to give them different restrictions, and scope each group to all workspaces or a specific subset to vary restrictions per workspace. A user can be in an all-workspaces group for a baseline plus a specific-workspace group that overrides it in select workspaces. Who can access a given workspace is still controlled separately by workspace invitations and permissions."
   },
   {
     question: "What is the default group?",

apps/docs/content/docs/en/platform/permissions.mdx

@@ -191,9 +191,9 @@ import { FAQ } from '@/components/ui/faq'
 <FAQ items={[
   { question: "What is the difference between organization roles and workspace permissions?", answer: "Organization roles (Owner, Admin, or Member) control who can manage the organization itself, including inviting people, creating shared workspaces, and handling billing. Workspace permissions (Read, Write, Admin) control what a user can do within a specific workspace, such as viewing, editing, or managing workflows. Internal members need both an organization role and a workspace permission to work within a shared workspace. External workspace members do not have an organization role in your org; they only have workspace-level access." },
   { question: "What happens to my shared workspaces if I cancel or downgrade my Team plan?", answer: "Existing shared workspaces remain accessible to current members, but new invitations are disabled until you upgrade back to a Team or Enterprise plan. No workspaces or members are deleted — the organization is simply dormant until billing is re-enabled." },
-  { question: "Can I restrict which integrations or model providers a team member can use?", answer: "Yes, on Enterprise-entitled organizations. Any organization owner or admin can create permission groups with fine-grained controls, including restricting allowed integrations and allowed model providers to specific lists. You can also disable access to MCP tools, custom tools, skills, and various platform features like the knowledge base, API keys, or Copilot on a per-group basis. Permission groups are scoped to the organization and apply to every workspace under it — a user belongs to at most one group per organization." },
+  { question: "Can I restrict which integrations or model providers a team member can use?", answer: "Yes, on Enterprise-entitled organizations. Any organization owner or admin can create permission groups with fine-grained controls, including restricting allowed integrations and allowed model providers to specific lists. You can also disable access to MCP tools, custom tools, skills, and various platform features like the knowledge base, API keys, or Copilot on a per-group basis. Permission groups are scoped to the organization and can govern either all workspaces or a specific subset — a user can belong to multiple groups but is governed by exactly one group in any given workspace." },
   { question: "What happens when a personal environment variable has the same name as a workspace variable?", answer: "The personal environment variable takes priority. When a workflow runs, if both a personal and workspace variable share the same name, the personal value is used. This allows individual users to override shared workspace configuration when needed." },
   { question: "Can an Admin remove the workspace owner?", answer: "No. The workspace owner cannot be removed from the workspace by anyone. Only the workspace owner can delete the workspace or transfer ownership to another user. Admins can do everything else, including inviting and removing other users and managing workspace settings." },
-  { question: "What are permission groups and how do they work?", answer: "Permission groups are an Enterprise access control feature that lets organization owners and admins define granular restrictions beyond the standard Read/Write/Admin roles. Groups are scoped to the organization and apply to every workspace under it: each user belongs to at most one group per organization. A permission group can hide UI sections (like trace spans, knowledge base, API keys, or deployment options), disable features (MCP tools, custom tools, skills, invitations), and restrict which integrations and model providers its members can access. Members are assigned manually, and an organization can designate one group as the default that governs everyone not explicitly assigned — including external workspace members. Execution-time enforcement is based on the organization that owns the workflow's workspace, not the user's current UI context." },
+  { question: "What are permission groups and how do they work?", answer: "Permission groups are an Enterprise access control feature that lets organization owners and admins define granular restrictions beyond the standard Read/Write/Admin roles. Groups are scoped to the organization and can govern either all workspaces or a specific subset. A user can belong to multiple groups, but at most one governs them in any given workspace: a workspace-specific group takes precedence over an all-workspaces group, which takes precedence over the organization's default group. A permission group can hide UI sections (like trace spans, knowledge base, API keys, or deployment options), disable features (MCP tools, custom tools, skills, invitations), and restrict which integrations and model providers its members can access. Members are assigned manually, and an organization can designate one group as the default (always all-workspaces) that governs everyone not explicitly assigned — including external workspace members. Execution-time enforcement is based on the organization that owns the workflow's workspace, not the user's current UI context." },
   { question: "How should I set up permissions for a new team member?", answer: "Start with the lowest permission level they need. Invite teammates to the organization as Members, then add them to the relevant workspace with Read permission if they only need visibility, Write if they need to create and run workflows, or Admin if they need to manage the workspace and its users. For clients, partners, or users who already belong to another Sim organization, use external workspace access so they can collaborate without joining your organization or consuming a seat." },
 ]} />