chore: apply review wording suggestions

Move the access-gap explanation ahead of the restriction steps, exclude service accounts from "every member" claims, align the CLI example with the docs wording, and trim comments that restated code.

cli/organizationmanage.go

@@ -73,7 +73,7 @@ func (r *RootCmd) editOrganization(orgContext *OrganizationContext) *serpent.Com
 				Command:     "coder organizations edit --default-org-member-roles organization-workspace-access,agents-access,organization-template-admin",
 			},
 			Example{
-				Description: "Restrict Coder Agents to members granted agents-access explicitly",
+				Description: "Restrict Coder Agents to members assigned agents-access directly",
 				Command:     "coder organizations edit --default-org-member-roles organization-workspace-access",
 			},
 			Example{

cli/testdata/coder_organizations_edit_--help.golden

@@ -10,7 +10,7 @@ USAGE:
        $ coder organizations edit --default-org-member-roles
   organization-workspace-access,agents-access,organization-template-admin
   
-    - Restrict Coder Agents to members granted agents-access explicitly:
+    - Restrict Coder Agents to members assigned agents-access directly:
   
        $ coder organizations edit --default-org-member-roles
   organization-workspace-access

coderd/rbac/roles.go

@@ -216,10 +216,9 @@ func ScopedRoleAgentsAccess(organizationID uuid.UUID) RoleIdentifier {
 
 // DefaultOrgMemberRoles is the deployment-wide default for the
 // organizations.default_org_member_roles column, applied to every new
-// organization at creation time: workspace access and Coder Agents access.
-// The column has no SQL DEFAULT, so this is the sole authoritative source:
-// every InsertOrganization call site must supply this value unless a
-// caller-chosen override is required.
+// organization at creation time. The column has no SQL DEFAULT, so this
+// is the sole authoritative source: every InsertOrganization call site
+// must supply this value unless a caller-chosen override is required.
 // Returned as a fresh slice each call to prevent accidental mutation of
 // the shared default through append or index assignment.
 func DefaultOrgMemberRoles() []string {

codersdk/rbacroles.go

@@ -8,8 +8,8 @@ const (
 	RoleUserAdmin     string = "user-admin"
 	RoleAuditor       string = "auditor"
 	// RoleAgentsAccess is the organization role that grants Coder Agents
-	// chat access. New organizations include it in their default member
-	// roles.
+	// chat access. Organizations include it in their default member roles
+	// unless an administrator removes it.
 	RoleAgentsAccess string = "agents-access"
 
 	RoleOrganizationAdmin                string = "organization-admin"

docs/admin/users/groups-roles.md

@@ -63,8 +63,8 @@ Coder ships the following organization roles:
 - **Organization Template Admin**: manages the organization's templates and provisioners, and reads its workspaces.
 - **Organization Auditor**: reads the organization's audit logs and connection logs, along with the resources those logs reference.
 - **Organization Workspace Access**: creates and operates the user's own workspaces in the organization.
-- **Coder Agents User**: uses [Coder Agents](../../ai-coder/agents/index.md) in the organization. Every member holds this role through the organization's [default member roles](./organizations.md#default-member-roles) unless an administrator removes it.
 - **Organization Workspace Creation Ban**: blocks creating and deleting workspaces in the organization, and overrides any role that would otherwise allow it.
+- **Coder Agents User**: uses [Coder Agents](../../ai-coder/agents/index.md) in the organization. Members other than service accounts hold this role through the organization's [default member roles](./organizations.md#default-member-roles) unless an administrator removes it.
 
 Organization Admin doesn't include SSH, application, or terminal access to workspaces other members own.
 A user with that role can read, build, stop, and delete those workspaces.

docs/ai-coder/agents/getting-started.md

@@ -76,8 +76,11 @@ It also provisions a workspace for tasks that need file access, command executio
 
 ## Control who can use Coder Agents
 
-Every organization member can use Coder Agents by default.
-Access comes from the **Coder Agents User** (`agents-access`) organization role, which each organization grants to all members through its [default member roles](../../admin/users/organizations.md#default-member-roles).
+Organization members can use Coder Agents by default.
+Access comes from the **Coder Agents User** (`agents-access`) organization role, which each organization grants to members through its [default member roles](../../admin/users/organizations.md#default-member-roles).
+
+Members who don't hold the role directly lose Coder Agents access when you remove **Coder Agents User** from the default roles.
+Role sync assigns roles at sign-in and doesn't store default roles, so members who get the role through role sync regain access at their next sign-in, and mapping the role in advance doesn't shorten the gap.
 
 To limit Coder Agents to a subset of members in an organization (requires a Premium license):
 
@@ -90,10 +93,7 @@ To limit Coder Agents to a subset of members in an organization (requires a Prem
 
 Keep the following behavior in mind:
 
-- Role sync runs when a user signs in.
-  After you remove the default, members who should keep access get the role at their next sign-in, and lose Coder Agents access until then.
-  Removing a user from the mapped IdP group takes effect at their next sign-in.
-- While `agents-access` is a default role, role sync doesn't store it on members, so configuring the mapping before you remove the default doesn't grant the role in advance.
+- Removing a user from the mapped IdP group or role removes their Coder Agents access at their next sign-in.
 - Owners and Organization Admins can always use Coder Agents, whatever the default roles are.
 - Service accounts don't inherit `agents-access` from the default roles.
   Assign the role to a service account directly if it needs Coder Agents.

docs/reference/cli/organizations_edit.md

@@ -21,7 +21,7 @@ coder organizations edit [flags]
 
      $ coder organizations edit --default-org-member-roles organization-workspace-access,agents-access,organization-template-admin
 
-  - Restrict Coder Agents to members granted agents-access explicitly:
+  - Restrict Coder Agents to members assigned agents-access directly:
 
      $ coder organizations edit --default-org-member-roles organization-workspace-access
 

site/src/api/typesGenerated.ts

@@ -8714,8 +8714,8 @@ export interface Role {
 /**
  * Ideally these roles would be generated from the rbac/roles.go package.
  * RoleAgentsAccess is the organization role that grants Coder Agents
- * chat access. New organizations include it in their default member
- * roles.
+ * chat access. Organizations include it in their default member roles
+ * unless an administrator removes it.
  */
 export const RoleAgentsAccess = "agents-access";
 

site/src/pages/OrganizationSettingsPage/CustomRolesPage/CustomRolesPageView.tsx

@@ -204,9 +204,8 @@ const DefaultRolesSection: FC<DefaultRolesSectionProps> = ({
 			<div className="text-sm">
 				{organization.default_org_member_roles.length === 0 ? (
 					<span className="text-content-secondary">
-						No default roles. Members have only the permissions of their
-						directly assigned roles, which excludes creating and using
-						workspaces and using Coder Agents.
+						No default roles. Members can create and use workspaces or use Coder
+						Agents only through directly assigned roles.
 					</span>
 				) : (
 					<DefaultRolesSummary