fix(docs): keep the shipped workspaces members anchor and classify the member update

- Pin the CLI reference heading for `sim workspaces members list` to the
  `#sim-workspaces-members` anchor it shipped under, through a reference-page
  counterpart of the existing legacy anchor map, and restore that heading in
  the docs compatibility baseline.
- Classify `updateWorkspaceMember` as non-destructive alongside
  `updateOrganizationMember`.
- Cover an inherited organization admin with no grant row: PATCH answers the
  documented 400 for every requested role and writes nothing.

Author: waleedlatif1

apps/docs/content/docs/cli/reference.mdx

@@ -8849,7 +8849,7 @@ sim workspaces fork-resources [options]
 
 API request and response schemas: [listWorkspaceForkResources](/api-reference/workspace-sync/listWorkspaceForkResources).
 
-### sim workspaces members list
+### sim workspaces members list [#sim-workspaces-members]
 
 List workspace members
 

apps/docs/scripts/fixtures/content-baseline.json

@@ -8555,8 +8555,8 @@
           "depth": 3
         },
         {
-          "title": "sim workspaces members list",
-          "url": "#sim-workspaces-members-list",
+          "title": "sim workspaces members",
+          "url": "#sim-workspaces-members",
           "depth": 3
         },
         {

apps/sim/lib/workspaces/__integration__/members.integration.ts

@@ -480,16 +480,33 @@ describe('v2 workspace member management against PostgreSQL', () => {
     const refusals = await Promise.all([
       call(admin, 'PATCH', f.users.wsOwner, { body: { role: 'read' } }),
       call(admin, 'PATCH', f.users.billing, { body: { role: 'read' } }),
-      call(admin, 'PATCH', f.users.orgOwner, { body: { role: 'write' } }),
-      call(admin, 'PATCH', f.users.orgOwner, { body: { role: 'admin' } }),
       call(admin, 'DELETE', f.users.orgOwner),
       call(admin, 'DELETE', f.users.billing),
     ])
-    expect(refusals.map((response) => response.status)).toEqual([400, 400, 400, 400, 400, 400])
+    expect(refusals.map((response) => response.status)).toEqual([400, 400, 400, 400])
     expect(await roleOf(f.users.wsOwner)).toBe('admin')
     expect(await roleOf(f.users.billing)).toBe('admin')
   })
 
+  it('refuses an inherited organization admin, who holds no grant row, whatever role is requested', async () => {
+    expect(await roleOf(f.users.orgOwner)).toBeNull()
+    for (const role of ['admin', 'write', 'read'] as const) {
+      const response = await call(key('admin'), 'PATCH', f.users.orgOwner, { body: { role } })
+      expect(response).toEqual({
+        status: 400,
+        retryAfter: null,
+        body: {
+          error: {
+            code: 'BAD_REQUEST',
+            message: 'Organization admins are workspace admins and their role cannot be changed',
+          },
+        },
+      })
+    }
+    expect(await roleOf(f.users.orgOwner)).toBeNull()
+    expect(await auditRows('member.role_changed')).toHaveLength(0)
+  })
+
   it('returns the roster member and audits the key owner as actor', async () => {
     const response = await call(key('admin'), 'PATCH', f.users.reader, { body: { role: 'write' } })
     expect(response.status).toBe(200)

packages/sim-cli/src/http/client.test.ts

@@ -447,6 +447,7 @@ describe('destructive operations are gated', () => {
     'createOrganizationInvitation',
     'resendOrganizationInvitation',
     'updateOrganizationMember',
+    'updateWorkspaceMember',
     'createPermissionGroup',
     'updatePermissionGroup',
     'addPermissionGroupMember',

scripts/generate-cli-docs.ts

@@ -466,6 +466,15 @@ const LEGACY_COMMAND_ANCHORS: Record<string, string> = {
     'wait-for-copy-and-deployment-readiness-exit-3-for-configuration-1-for-failure-or-4-for-timeout',
 }
 
+/**
+ * Reference-page anchors a renamed command keeps, so links to the spelling it
+ * shipped under still land on it. `workspaces members` became a group whose
+ * default subcommand is `list`.
+ */
+const LEGACY_REFERENCE_ANCHORS: Record<string, string> = {
+  'workspaces members list': 'sim-workspaces-members',
+}
+
 const VERB_ORDER = [
   'list',
   'ls',
@@ -913,7 +922,9 @@ function renderCommand(entry: DocumentedCommand, options: RenderOptions = {}): s
   const description = entry.command.description()
   const operation = operationOf(entry.command)
   const spec = operation ? CLI_CONTRACT[operation] : undefined
-  const anchor = commandHeadings ? undefined : LEGACY_COMMAND_ANCHORS[entry.path.join(' ')]
+  const anchor = (commandHeadings ? LEGACY_REFERENCE_ANCHORS : LEGACY_COMMAND_ANCHORS)[
+    entry.path.join(' ')
+  ]
   const lines = [`${'#'.repeat(level)} ${escapeProse(heading)}${anchor ? ` [#${anchor}]` : ''}`, '']
   if (commandHeadings && description) lines.push(escapeProse(sentenceCase(description)), '')
   if (!commandHeadings) {