fix(api): align v2 workspace member errors and keep the old CLI spelling

- Answer a role change for a non-member with 404 "Member not found", as
  the organization member route does, and drop the post-write re-read.
- Answer role-change contention with 503 and Retry-After, like removal;
  the internal route keeps its 409.
- Keep `sim workspaces members` listing members as the default
  subcommand of the new group.
- Correct the member route prose and the workspaceId parameter wording.
- Give each integration test its own fixture and cover contention.

Author: waleedlatif1

apps/docs/openapi-v2-resources.json

@@ -425,7 +425,7 @@
       "patch": {
         "operationId": "updateWorkspaceMember",
         "summary": "Update workspace member",
-        "description": "Change one existing member’s workspace role. Requires workspace Admin access. Only existing members can be changed; add people with Create workspace invitations. You cannot lower your own role, and organization Admins, the workspace owner, and the workspace billing account always keep Admin. Members whose organization membership an identity provider manages cannot be changed here. Requesting the role a member already holds changes nothing and records no audit entry. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "description": "Change one existing member’s workspace role. Requires workspace Admin access. Only existing members can be changed; anyone else is Not found, and people are added with Create workspace invitations. You cannot lower your own role, and organization Admins, the workspace owner, and the workspace billing account always keep Admin. Members whose organization membership an identity provider manages cannot be changed here. Requesting the role a member already holds changes nothing and records no audit entry, except that an organization Admin is refused whatever role is requested. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workspaces.permissions.update",
         "x-oauth-scope": "api:write",
         "tags": ["Workspaces"],
@@ -442,12 +442,12 @@
             "name": "workspaceId",
             "in": "path",
             "required": true,
-            "description": "Workspace to retrieve.",
+            "description": "Workspace the member belongs to.",
             "schema": {
               "type": "string",
               "minLength": 1,
               "maxLength": 128,
-              "description": "Workspace to retrieve."
+              "description": "Workspace the member belongs to."
             }
           },
           {
@@ -555,7 +555,7 @@
       "delete": {
         "operationId": "removeWorkspaceMember",
         "summary": "Remove workspace member",
-        "description": "Remove a member’s workspace access, or leave the workspace by naming yourself. Removing someone else requires workspace Admin access; any member may leave. The last Admin cannot leave, organization Admins hold access through their organization role and cannot be removed here, and the workspace billing account cannot be removed until billing is reassigned. Removing the workspace owner transfers ownership to the billing account. When this was the member’s last workspace in its organization, their organization membership and seat are removed too and all of their sessions end. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
+        "description": "Remove a member’s workspace access, or leave the workspace by naming yourself. Removing someone else requires workspace Admin access; any member may leave. The last Admin cannot leave, organization Admins hold access through their organization role and cannot be removed here, and the workspace billing account cannot be removed until billing is reassigned. Removing the workspace owner transfers ownership to the billing account. When this was the member’s last workspace in its organization, their organization membership and seat are removed too and all of their sessions end, since this endpoint is called with an API key or OAuth token rather than from a signed-in browser session. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.",
         "x-sim-operation": "workspaces.members.remove",
         "x-oauth-scope": "api:write",
         "tags": ["Workspaces"],
@@ -572,12 +572,12 @@
             "name": "workspaceId",
             "in": "path",
             "required": true,
-            "description": "Workspace to retrieve.",
+            "description": "Workspace the member belongs to.",
             "schema": {
               "type": "string",
               "minLength": 1,
               "maxLength": 128,
-              "description": "Workspace to retrieve."
+              "description": "Workspace the member belongs to."
             }
           },
           {

apps/sim/lib/api/contracts/v2/openapi/resources.ts

@@ -764,7 +764,7 @@ const declaredRoutes = [
       applicationOperation: workspacePermissionOperations.update,
       operationId: 'updateWorkspaceMember',
       summary: 'Update workspace member',
-      description: `Change one existing member’s workspace role. Requires workspace Admin access. Only existing members can be changed; add people with Create workspace invitations. You cannot lower your own role, and organization Admins, the workspace owner, and the workspace billing account always keep Admin. Members whose organization membership an identity provider manages cannot be changed here. Requesting the role a member already holds changes nothing and records no audit entry. ${WORKSPACE_API_KEY_DENIED}`,
+      description: `Change one existing member’s workspace role. Requires workspace Admin access. Only existing members can be changed; anyone else is Not found, and people are added with Create workspace invitations. You cannot lower your own role, and organization Admins, the workspace owner, and the workspace billing account always keep Admin. Members whose organization membership an identity provider manages cannot be changed here. Requesting the role a member already holds changes nothing and records no audit entry, except that an organization Admin is refused whatever role is requested. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'The member with their updated workspace role.' },
     }),
@@ -798,7 +798,7 @@ const declaredRoutes = [
       applicationOperation: removeWorkspaceMemberOperation,
       operationId: 'removeWorkspaceMember',
       summary: 'Remove workspace member',
-      description: `Remove a member’s workspace access, or leave the workspace by naming yourself. Removing someone else requires workspace Admin access; any member may leave. The last Admin cannot leave, organization Admins hold access through their organization role and cannot be removed here, and the workspace billing account cannot be removed until billing is reassigned. Removing the workspace owner transfers ownership to the billing account. When this was the member’s last workspace in its organization, their organization membership and seat are removed too and all of their sessions end. ${WORKSPACE_API_KEY_DENIED}`,
+      description: `Remove a member’s workspace access, or leave the workspace by naming yourself. Removing someone else requires workspace Admin access; any member may leave. The last Admin cannot leave, organization Admins hold access through their organization role and cannot be removed here, and the workspace billing account cannot be removed until billing is reassigned. Removing the workspace owner transfers ownership to the billing account. When this was the member’s last workspace in its organization, their organization membership and seat are removed too and all of their sessions end, since this endpoint is called with an API key or OAuth token rather than from a signed-in browser session. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_CONFLICT_ERRORS,
       success: { description: 'Acknowledgement that workspace access was removed.' },
     }),

apps/sim/lib/api/contracts/v2/workspaces.ts

@@ -121,8 +121,9 @@ export const v2ListWorkspaceMembersContract = defineRouteContract({
   response: { mode: 'json', schema: v2CursorListResponse(v2WorkspaceMemberSchema) },
 })
 
-const v2WorkspaceMemberParamsSchema = v2WorkspaceParamsSchema
-  .extend({
+const v2WorkspaceMemberParamsSchema = z
+  .object({
+    workspaceId: workspaceIdSchema.describe('Workspace the member belongs to.'),
     userId: requiredFieldSchema('User ID is required')
       .max(MAX_ID_LENGTH, 'User ID is too long')
       .describe('User identifier of the workspace member, as returned by List workspace members.'),

apps/sim/lib/api/mcp/generated/v2-operations.ts

@@ -2450,7 +2450,7 @@ export const V2_MCP_OPERATIONS = {
     contract: v2RemoveWorkspaceMemberContract,
     summary: 'Remove workspace member',
     description:
-      'Remove a member’s workspace access, or leave the workspace by naming yourself. Removing someone else requires workspace Admin access; any member may leave. The last Admin cannot leave, organization Admins hold access through their organization role and cannot be removed here, and the workspace billing account cannot be removed until billing is reassigned. Removing the workspace owner transfers ownership to the billing account. When this was the member’s last workspace in its organization, their organization membership and seat are removed too and all of their sessions end. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Remove a member’s workspace access, or leave the workspace by naming yourself. Removing someone else requires workspace Admin access; any member may leave. The last Admin cannot leave, organization Admins hold access through their organization role and cannot be removed here, and the workspace billing account cannot be removed until billing is reassigned. Removing the workspace owner transfers ownership to the billing account. When this was the member’s last workspace in its organization, their organization membership and seat are removed too and all of their sessions end, since this endpoint is called with an API key or OAuth token rather than from a signed-in browser session. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/members/[userId]/route').then(
@@ -3025,7 +3025,7 @@ export const V2_MCP_OPERATIONS = {
     contract: v2UpdateWorkspaceMemberContract,
     summary: 'Update workspace member',
     description:
-      'Change one existing member’s workspace role. Requires workspace Admin access. Only existing members can be changed; add people with Create workspace invitations. You cannot lower your own role, and organization Admins, the workspace owner, and the workspace billing account always keep Admin. Members whose organization membership an identity provider manages cannot be changed here. Requesting the role a member already holds changes nothing and records no audit entry. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
+      'Change one existing member’s workspace role. Requires workspace Admin access. Only existing members can be changed; anyone else is Not found, and people are added with Create workspace invitations. You cannot lower your own role, and organization Admins, the workspace owner, and the workspace billing account always keep Admin. Members whose organization membership an identity provider manages cannot be changed here. Requesting the role a member already holds changes nothing and records no audit entry, except that an organization Admin is refused whatever role is requested. Workspace API keys return `403`; use a personal API key or scoped OAuth token.\n\nOAuth scope: `api:write`.',
     workspaceKeyUnsupported: true,
     handler: () =>
       import('@/app/api/v2/workspaces/[workspaceId]/members/[userId]/route').then(