simstudioai · icecrasher321 · Jun 20, 2026 · Jun 20, 2026 · Jun 20, 2026 · Jun 20, 2026
diff --git a/apps/docs/content/docs/en/platform/enterprise/access-control.mdx b/apps/docs/content/docs/en/platform/enterprise/access-control.mdx
@@ -7,22 +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 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.
+Access Control lets organization admins define permission groups that restrict what each set of users 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**. The organization's **default group** governs everyone org-wide; every other group targets a **specific set of workspaces** and, by default, governs **all members of those workspaces** (including external members) — or only specific members once you add them. A user 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, 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.
+Access control is built around **permission groups**. Each group belongs to a specific organization and has a name, an optional description, a **workspace scope**, an optional **member** list, and a configuration that defines what its members can and cannot do. The organization's single **default group** is org-wide; every other group targets a **specific set of workspaces**. A non-default group with **no members** governs **all members** of its workspaces (including external members); adding members narrows it to only those people. Personal workspaces that do not belong to an organization have no permission groups.
 
-Sim resolves the governing group for a user in a workspace deterministically, with **specific-over-all precedence**:
+Sim resolves the governing group for a user in a workspace deterministically:
 
-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
+1. a non-default group targeting that workspace that the user is an **explicit member** of takes precedence; otherwise
+2. a non-default group targeting that workspace that has **no members** (so it governs all members of the workspace, including external members) 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.
+Assignment-time checks keep this unambiguous: a workspace has at most one all-members group, and a user is an explicit member of at most one group per workspace.
 
 When a user runs a workflow or uses Mothership, Sim reads the resolved group's configuration and applies it:
 
@@ -41,11 +41,15 @@ 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. 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.
+Click **+ Create** and enter a name (required) and optional description. A group either targets a **specific set of workspaces** (pick them from the multi-select) or is the **organization default group**. A workspace-scoped group applies to **all members** of its workspaces by default, including external members — you can narrow it to specific people later. Marking the group as the **default** makes it govern every workspace in the organization and every member not covered by another group (including external members); only one group per organization can be the default, and the default always applies to all workspaces.
 
 ### 3. Configure permissions
 
-Click **Details** on a group, then open **Configure Permissions**. There are three tabs.
+Click **Details** on a group, then open **Configure Permissions**. Non-default groups have a **Members** tab plus three restriction tabs; the default group has only the restriction tabs.
+
+#### Members
+
+A workspace-scoped group with **no members** applies to everyone in its workspaces (including external members). Add members here — searching your organization by name or email — to restrict the group to only those people; removing every member returns it to governing everyone. The default group ignores members and has no Members tab.
 
 #### Model Providers
 
@@ -135,13 +139,15 @@ Controls visibility of platform features and modules.
 |---------|-------------------|
 | Invitations | Disables the ability to invite new members to the workspace |
 
-### 4. Add members
+### 4. Choose who it applies to
+
+A workspace-scoped group applies to **all members of its workspaces by default** — including external members. To restrict it to specific people instead, open **Configure Permissions → Members** and add members by searching your organization by name or email. Removing every member returns the group to governing everyone in its workspaces.
 
-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.
+A user is governed by one group per workspace, so adding a user is rejected when it would conflict with another of their groups on a shared workspace (skipped rather than added in bulk). The default group ignores members entirely — it always governs everyone not covered by a workspace group.
 
-You can also change a group's workspace scope at any time from the **Workspaces** row in the Details view.
+Manage which workspaces a group governs from the **Workspaces** list in the group's **Details** view (Add and Remove). A non-default group must always target at least one workspace.
 
-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.
+External workspace members (people who have access to a workspace but belong to a different organization) can't be added as named members, but a workspace-scoped group with no members — and the organization default group — still governs them.
 
 ---
 
@@ -169,10 +175,11 @@ When a user opens Mothership, their permission group is read before any block or
 ## User membership rules
 
 - 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.
+- For a given workspace, a non-default group the user is an **explicit member** of takes precedence over a non-default **all-members** group (one with no members) targeting that workspace, which takes precedence over the organization's **default group**.
+- A workspace has **at most one all-members group**, and a user is an explicit member of **at most one** group per workspace. Adding a user, adding a workspace, or removing a group's last member is rejected when it would violate this — memberships and scopes are never silently moved.
+- A workspace-scoped group with **no members** governs everyone in its workspaces (including external members); add members to narrow it to specific people.
+- Users not covered by any workspace 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 the **default group**; it always applies to all workspaces, ignores members, and also governs external workspace members.
 - Personal or grandfathered workspaces that do not belong to an organization have no permission groups.
 
 ---
@@ -188,27 +195,31 @@ When a user opens Mothership, their permission group is read before any block or
   },
   {
     question: "Can a user be in multiple permission groups?",
-    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."
+    answer: "Yes. A user can belong to multiple permission groups, but only one governs them in any given workspace. A group they're an explicit member of takes precedence over an all-members group (one with no members) on that workspace, which takes precedence over the organization's default group. A workspace has at most one all-members group, and a user is an explicit member of at most one group per workspace."
+  },
+  {
+    question: "Does a permission group apply to everyone in its workspaces, or specific people?",
+    answer: "By default, a workspace-scoped group applies to all members of its workspaces, including external members. To restrict it to specific people, open Configure Permissions → Members and add them; the group then governs only those members. Removing every member returns it to governing everyone in its workspaces."
   },
   {
     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."
+    answer: "Every non-default group targets a specific set of workspaces — choose them when you create the group or from the Workspaces list in its Details view. Only the organization default group is org-wide."
   },
   {
     question: "What governs a user who has no permission group assigned?",
-    answer: "If the organization has a default group, it governs every member (and external workspace member) who is not explicitly assigned to another group. If no default group is set, those users have no restrictions — all blocks, model providers, and platform features are available to them."
+    answer: "In a workspace targeted by an all-members group (one with no members), that group governs them. Otherwise the organization's default group governs them if one is set. If neither applies, they have no restrictions — all blocks, model providers, and platform features are available."
   },
   {
     question: "Does Mothership respect the same restrictions as the executor?",
     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 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."
+    answer: "Yes. Scope each group to the workspaces it should govern, and either let it apply to everyone there or add members to target specific people. A workspace can have one all-members group plus additional groups that target specific people, who are governed by their own group instead. Who can access a given workspace is still controlled separately by workspace invitations and permissions."
   },
   {
     question: "What is the default group?",
-    answer: "The default group is the single group per organization that governs everyone not explicitly assigned to another group, including external workspace members operating in the organization's workspaces. Only one group per organization can be the default at a time. If no default is set, ungrouped users have no restrictions."
+    answer: "The default group is the single org-wide group that governs everyone not covered by a workspace group, including external workspace members. It always applies to all workspaces and ignores members. Only one per organization; if none is set, ungrouped users have no restrictions."
   }
 ]} />
 

diff --git a/apps/docs/content/docs/en/platform/permissions.mdx b/apps/docs/content/docs/en/platform/permissions.mdx
@@ -226,6 +226,6 @@ import { FAQ } from '@/components/ui/faq'
   { question: "What happens when a personal environment variable has the same name as a workspace variable?", answer: "The workspace variable wins. When a workflow runs, the resolver checks workspace variables first and falls back to a personal variable only when no workspace variable shares that name. This keeps shared, team-managed values authoritative in production workflows." },
   { question: "Can an Admin remove the workspace owner?", answer: "On a shared (organization) workspace, yes — any Admin can remove the workspace Owner, and ownership passes to the organization's owner so the workspace always has one. The organization's owner is the single account that can't be removed this way, since they're the final fallback. On your personal workspace you are the Owner and can't remove yourself. The Owner is not a higher permission tier than Admin: every Admin — including those who inherit the role from their organization — can manage members and settings and delete the workspace." },
   { question: "Who can manage a workspace's credentials and secrets?", answer: "Workspace Admins are automatically Credential Admins of the workspace's shared credentials — OAuth connections, service accounts, and workspace environment variables — so they can use, edit, delete, and share them, and run workflows that rely on them. Organization Owners and Admins get this too because they are workspace Admins everywhere. Read and Write members get use-only access to shared credentials unless they are explicitly made a Credential Admin. Personal environment variables are never shared; they stay private to their owner." },
-  { 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. Restrictions are enforced based on the organization that owns the workflow's workspace, not on which workspace you're currently viewing." },
+  { 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. The organization's default group is org-wide; every other group targets specific workspaces and, by default, governs all members of those workspaces (including external members) — add members to restrict it to specific people. A user is governed by one group per workspace: a group they're an explicit member of takes precedence over an all-members group (one with no members) on that workspace, 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. Only one group per organization can be the default; it ignores members and governs everyone not covered by a workspace group, including external members. Restrictions are enforced based on the organization that owns the workflow's workspace, not on which workspace you're currently viewing." },
   { 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." },
 ]} />