picked 0.0.101 → 0.0.102-next.2

package/docs/reference/management-api/schema/organization.md

@@ -6,13 +6,14 @@ generated: true
 
 # Organization schema
 
-The operations and types that `organization.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
 
 ## Queries
 
 ### `organization`
 
-Fetch a single organisation by ID or slug. Requires authentication.
+Reads an organisation by ID or slug. Null when no organisation matches.
+Scope: `ORGANIZATION_READ`.
 
 ```graphql
 organization(input: OrganizationInput!): Organization @auth
@@ -20,7 +21,8 @@ organization(input: OrganizationInput!): Organization @auth
 
 ### `organizations`
 
-List organisations the authenticated user belongs to. Requires authentication.
+Lists the organisations the user belongs to. `search` matches a case-insensitive substring of
+the name. Empty for an API key.
 
 ```graphql
 organizations(first: Int, after: String, search: String, sortKey: OrganizationSortKeys = NAME, reverse: Boolean = false): OrganizationConnection! @auth
@@ -30,7 +32,8 @@ organizations(first: Int, after: String, search: String, sortKey: OrganizationSo
 
 ### `organizationCreate`
 
-Create a new organisation. Requires scope: `ORGANIZATION_CREATE`.
+Creates an organisation owned by the calling user.
+Scope: `ORGANIZATION_CREATE`.
 
 ```graphql
 organizationCreate(input: OrganizationCreateInput!): OrganizationCreatePayload! @auth
@@ -38,7 +41,8 @@ organizationCreate(input: OrganizationCreateInput!): OrganizationCreatePayload!
 
 ### `organizationUpdate`
 
-Update an organisation. Requires scope: `ORGANIZATION_UPDATE`.
+Updates an organisation.
+Scope: `ORGANIZATION_UPDATE`.
 
 ```graphql
 organizationUpdate(input: OrganizationUpdateInput!): OrganizationUpdatePayload! @auth
@@ -46,7 +50,8 @@ organizationUpdate(input: OrganizationUpdateInput!): OrganizationUpdatePayload!
 
 ### `organizationDelete`
 
-Delete an organisation. Requires scope: `ORGANIZATION_DELETE`.
+Deletes an organisation.
+Scope: `ORGANIZATION_DELETE`.
 
 ```graphql
 organizationDelete(input: OrganizationDeleteInput!): OrganizationDeletePayload! @auth
@@ -54,7 +59,9 @@ organizationDelete(input: OrganizationDeleteInput!): OrganizationDeletePayload!
 
 ### `organizationMemberInvite`
 
-Invite a member to an organisation. Requires scope: `ORGANIZATION_INVITATIONS_CREATE`.
+Invites an email address to an organisation and emails the invitee. `delivery` says which
+email went out.
+Scope: `ORGANIZATION_INVITATIONS_CREATE`.
 
 ```graphql
 organizationMemberInvite(input: OrganizationMemberInviteInput!): OrganizationMemberInvitePayload! @auth
@@ -62,7 +69,8 @@ organizationMemberInvite(input: OrganizationMemberInviteInput!): OrganizationMem
 
 ### `organizationInvitationAccept`
 
-Accept an organisation invitation. Requires authentication.
+Accepts an invitation, making the calling user a member with the scopes it carries. The
+invitation is used up. An unknown or expired token, or an existing membership, fails.
 
 ```graphql
 organizationInvitationAccept(input: OrganizationInvitationAcceptInput!): OrganizationInvitationAcceptPayload! @auth
@@ -70,7 +78,7 @@ organizationInvitationAccept(input: OrganizationInvitationAcceptInput!): Organiz
 
 ### `organizationInvitationDecline`
 
-Decline an organisation invitation. Requires authentication.
+Declines an invitation addressed to the calling user's email address and deletes it.
 
 ```graphql
 organizationInvitationDecline(input: OrganizationInvitationDeclineInput!): OrganizationInvitationDeclinePayload! @auth
@@ -78,7 +86,8 @@ organizationInvitationDecline(input: OrganizationInvitationDeclineInput!): Organ
 
 ### `organizationInvitationRevoke`
 
-Revoke an organisation invitation. Requires scope: `ORGANIZATION_INVITATIONS_DELETE`.
+Revokes a pending invitation, so its token stops working.
+Scope: `ORGANIZATION_INVITATIONS_DELETE`.
 
 ```graphql
 organizationInvitationRevoke(input: OrganizationInvitationRevokeInput!): OrganizationInvitationRevokePayload! @auth
@@ -86,7 +95,9 @@ organizationInvitationRevoke(input: OrganizationInvitationRevokeInput!): Organiz
 
 ### `organizationMemberRemove`
 
-Remove a member from an organisation. Requires scope: `ORGANIZATION_MEMBERS_DELETE`.
+Removes a member from an organisation, with every scope they held there. The primary owner
+cannot be removed.
+Scope: `ORGANIZATION_MEMBERS_DELETE`.
 
 ```graphql
 organizationMemberRemove(input: OrganizationMemberRemoveInput!): OrganizationMemberRemovePayload! @auth
@@ -94,10 +105,10 @@ organizationMemberRemove(input: OrganizationMemberRemoveInput!): OrganizationMem
 
 ### `organizationMemberScopesUpdate`
 
-Set the scopes a member holds in an organisation. Requires
-`ORGANIZATION_MEMBERS_MANAGE_SCOPES` reaching that organisation. The target
-must be a member. A caller may not grant a scope they do not themselves hold,
-and may not edit their own scopes.
+Sets the scopes a member holds in an organisation. The caller cannot edit their own scopes,
+grant a scope they do not hold, or take `ORGANIZATION_MEMBERS_MANAGE_SCOPES` from the primary
+owner.
+Scope: `ORGANIZATION_MEMBERS_MANAGE_SCOPES`.
 
 ```graphql
 organizationMemberScopesUpdate(input: OrganizationMemberScopesUpdateInput!): OrganizationMemberScopesUpdatePayload! @auth
@@ -105,11 +116,9 @@ organizationMemberScopesUpdate(input: OrganizationMemberScopesUpdateInput!): Org
 
 ### `organizationClientManagerScopesUpdate`
 
-Set the scopes a client manager holds in one organisation. Requires
-`STAFF_INVITE_CLIENT_MANAGER` at root. The target must be a client manager,
-and a caller may not edit their own scopes. A client manager may add or
-remove only scopes their own client-manager grant in that organisation
-carries; a super admin may set any.
+Sets the scopes a client manager holds in one organisation. The caller cannot edit their own
+scopes, and a client manager can add or remove only scopes they hold there themselves.
+Scope: `STAFF_INVITE_CLIENT_MANAGER`.
 
 ```graphql
 organizationClientManagerScopesUpdate(input: OrganizationClientManagerScopesUpdateInput!): OrganizationClientManagerScopesUpdatePayload! @auth
@@ -121,19 +130,14 @@ organizationClientManagerScopesUpdate(input: OrganizationClientManagerScopesUpda
 
 ```graphql
 """
-Sort keys accepted by `organizations(...)` and `User.organizations(...)`.
-
-Pair with `reverse: true` to flip the order (e.g. `NAME` + `reverse: false`
-sorts A→Z; `CREATED_AT` + `reverse: true` sorts newest-first).
+The orders an organisation list can take. `reverse: true` flips the order.
 """
 enum OrganizationSortKeys {
-  """Sort by organisation `name` (alphabetical)."""
+  """By name, A to Z."""
   NAME
-  """Sort by `createdAt`."""
+  """By creation time, oldest first."""
   CREATED_AT
-  """
-  Sort by `updatedAt`. Pair with `reverse: true` for most-recently-changed first.
-  """
+  """By last change, oldest first."""
   UPDATED_AT
 }
 ```
@@ -142,19 +146,13 @@ enum OrganizationSortKeys {
 
 ```graphql
 """
-Invitation type. Historically, organisations could issue 24-hour multi-
-use invitations; that capability has been retired. All invitations are
-now single-use with a 30-day expiry.
-
-WARNING: This enum is retained for backwards compatibility with the
-deprecated `invitationType` argument on `organizationMemberInvite` and
-the deprecated `OrganizationInvitation.invitationType` field. Do not
-branch on it in new code.
+The kind of an invitation. Every invitation is single-use and expires 30 days after it is
+created.
 """
 enum InvitationType {
-  """Single-use invitation that expires on acceptance or after 30 days."""
+  """Single-use, expiring after 30 days."""
   ONE_TIME @deprecated(reason: "All invitations are now single-use with 30-day expiration")
-  """Deprecated. Previously allowed 24-hour multi-use invitations."""
+  """Multi-use, expiring after 24 hours. Not issued."""
   TWENTY_FOUR_HOUR @deprecated(reason: "All invitations are now single-use with 30-day expiration")
 }
 ```
@@ -163,52 +161,51 @@ enum InvitationType {
 
 ```graphql
 """
-An organisation — the top-level tenancy boundary for projects, API keys,
-integrations, and members.
-
-Every project, API key, and integration belongs to exactly one
-organisation. The set of scopes the current viewer holds in this
-organisation is available on `viewerScopes`; use it to drive
-client-side UX (which buttons to show, which actions to gate).
+The top level of Picked. It holds your projects, members, API keys and integrations.
 """
 type Organization {
-  """Unique organisation identifier."""
+  """The ID of the organisation."""
   id: ID!
-  """Display name of the organisation."""
+  """The name of the organisation."""
   name: String!
   """
-  URL-friendly slug for the organisation. Used in dashboard URLs and as a stable handle for the organisation.
+  The unique handle of the organisation in dashboard URLs. Null when it has none.
   """
   slug: String
-  """When this organisation was created."""
+  """When the organisation was created."""
   createdAt: DateTime!
-  """When this organisation was last updated."""
+  """When the organisation last changed."""
   updatedAt: DateTime!
   """
-  Whether every member must hold an `AAL2` session. A member of an organisation
-  with this on is held to the MFA policy on every request, whichever
-  organisation the request names.
+  Whether every member must hold an `AAL2` session. A member of such an organisation is held to
+  it on every request, whichever organisation the request names.
   """
   requireMfa: Boolean!
-  """Members of this organisation."""
+  """
+  The members of the organisation. Picked staff are not listed.
+  Scope: `ORGANIZATION_MEMBERS_READ`.
+  """
   members(first: Int, after: String): OrganizationMemberConnection!
-  """Pending invitations for this organisation."""
+  """
+  The unexpired invitations of the organisation, newest first.
+  Scope: `ORGANIZATION_INVITATIONS_READ`.
+  """
   invitations(first: Int, after: String): OrganizationInvitationConnection!
   """
-  Projects within this organisation. Filter by name with `search`
-  (case-insensitive substring) and order with `sortKey` (default `NAME`) plus
-  `reverse`.
+  The projects in the organisation. `search` matches a case-insensitive substring of the name.
+  Scope: `ORGANIZATION_PROJECTS_READ`.
   """
   projects(first: Int, after: String, search: String, sortKey: ProjectSortKeys = NAME, reverse: Boolean = false): ProjectConnection!
-  """API keys for this organisation."""
-  apiKeys(first: Int, after: String): ApiKeyConnection!
   """
-  Scopes available to the current viewer in this organisation. Drives client-side UX gating.
+  The API keys of the organisation.
+  Scope: `ORGANIZATION_API_KEYS_READ`.
   """
+  apiKeys(first: Int, after: String): ApiKeyConnection!
+  """The scopes the viewer holds in the organisation."""
   viewerScopes: [Scope!]!
   """
-  Every client manager, with the scopes their client-manager grant carries in
-  this organisation. Empty unless the viewer holds `STAFF_READ` at root.
+  Every client manager, with the scopes they hold in the organisation. Empty unless the viewer
+  holds `STAFF_READ`.
   """
   clientManagerAccess: [OrganizationClientManagerAccess!]!
 }
@@ -217,34 +214,23 @@ type Organization {
 ### `OrganizationMember`
 
 ```graphql
-"""
-A user's membership in an organisation. Carries the user's identifying
-fields denormalised from `auth.users`, plus the role and `joinedAt`
-timestamp.
-
-Member-level operations (`organizationMemberScopesUpdate`,
-`organizationMemberRemove`) require the corresponding scope on the
-parent organisation.
-"""
+"""A person in an organisation."""
 type OrganizationMember {
-  """Unique member identifier (the membership row id, not the user id)."""
+  """The ID of the member's user."""
   id: ID!
-  """Email address of the member."""
+  """The email address of the member. Null when unknown."""
   userEmail: String
-  """First name of the member."""
+  """The first name of the member. Null when unknown."""
   userFirstName: String
-  """Last name of the member."""
+  """The last name of the member. Null when unknown."""
   userLastName: String
-  """When the member joined the organisation."""
+  """The time of the request. The join time is not recorded."""
   joinedAt: DateTime!
-  """
-  Whether this member holds a verified MFA factor. Resolved for the whole page in one batched lookup.
-  """
+  """Whether the member has a verified MFA factor."""
   mfaState: MfaState!
   """
-  The scope grants this member holds in the organisation, one entry per
-  location. Empty unless the viewer holds `ORGANIZATION_MEMBERS_MANAGE_SCOPES`
-  reaching this organisation.
+  The scopes the member holds in the organisation, one entry per location. Empty unless the
+  viewer holds `ORGANIZATION_MEMBERS_MANAGE_SCOPES` in the organisation.
   """
   scopeGrants: [MemberScopeGrant!]!
 }
@@ -253,11 +239,13 @@ type OrganizationMember {
 ### `MemberScopeGrant`
 
 ```graphql
-"""A set of scopes a member holds at one location within an organisation."""
+"""The scopes a member holds at one location in an organisation."""
 type MemberScopeGrant {
-  """The project the scopes apply to, or null for the organisation itself."""
+  """
+  The ID of the project the scopes apply to. Null for the organisation itself.
+  """
   projectId: ID
-  """The scopes held at that location."""
+  """The scopes held at the location."""
   scopes: [Scope!]!
 }
 ```
@@ -266,15 +254,14 @@ type MemberScopeGrant {
 
 ```graphql
 """
-A client manager and the scopes they hold in one organisation, on top of the
-root grant that reaches every organisation.
+A client manager and the scopes they hold in one organisation, on top of the root grant that
+reaches every organisation.
 """
 type OrganizationClientManagerAccess {
   """The client manager."""
   user: AdminUser!
   """
-  The scopes their client-manager grant carries on this organisation. Empty
-  when they hold none here.
+  The scopes the client manager holds in the organisation. Empty when they hold none.
   """
   scopes: [Scope!]!
 }
@@ -283,11 +270,11 @@ type OrganizationClientManagerAccess {
 ### `OrganizationMemberEdge`
 
 ```graphql
-"""Edge type for `OrganizationMemberConnection`."""
+"""A member in a page of results."""
 type OrganizationMemberEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
-  """The organisation member."""
+  """The member."""
   node: OrganizationMember!
 }
 ```
@@ -295,13 +282,13 @@ type OrganizationMemberEdge {
 ### `OrganizationMemberConnection`
 
 ```graphql
-"""Relay-style connection of organisation members."""
+"""A page of organisation members."""
 type OrganizationMemberConnection {
-  """List of member edges."""
+  """The edges in this page."""
   edges: [OrganizationMemberEdge!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of members."""
+  """The total number of members."""
   totalCount: Int!
 }
 ```
@@ -310,27 +297,19 @@ type OrganizationMemberConnection {
 
 ```graphql
 """
-An invitation to join an organisation. Created via
-`organizationMemberInvite`, accepted via `organizationInvitationAccept`,
-declined via `organizationInvitationDecline`, and revoked by the inviter
-via `organizationInvitationRevoke`.
-
-Invitations expire 30 days after creation (server-enforced; see
-`expiresAt`). Once accepted, the row remains for audit but cannot be
-re-accepted.
+An offer to join an organisation, sent to an email address. It is single-use, expires 30 days
+after it is created, and is removed once accepted, declined or revoked.
 """
 type OrganizationInvitation {
-  """Unique invitation identifier."""
+  """The ID of the invitation."""
   id: ID!
-  """
-  Invitation type — retained for backwards compatibility. All invitations are now single-use.
-  """
+  """Always `ONE_TIME`."""
   invitationType: InvitationType! @deprecated(reason: "All invitations are now single-use. This field will be removed.")
-  """When this invitation was created."""
+  """When the invitation was created."""
   createdAt: DateTime!
-  """When this invitation expires."""
+  """When the invitation expires."""
   expiresAt: DateTime!
-  """Email address of the invited user."""
+  """The email address the invitation was sent to."""
   userEmail: String
 }
 ```
@@ -338,11 +317,11 @@ type OrganizationInvitation {
 ### `OrganizationInvitationEdge`
 
 ```graphql
-"""Edge type for `OrganizationInvitationConnection`."""
+"""An invitation in a page of results."""
 type OrganizationInvitationEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
-  """The organisation invitation."""
+  """The invitation."""
   node: OrganizationInvitation!
 }
 ```
@@ -350,13 +329,13 @@ type OrganizationInvitationEdge {
 ### `OrganizationInvitationConnection`
 
 ```graphql
-"""Relay-style connection of organisation invitations."""
+"""A page of organisation invitations."""
 type OrganizationInvitationConnection {
-  """List of invitation edges."""
+  """The edges in this page."""
   edges: [OrganizationInvitationEdge!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of invitations."""
+  """The total number of unexpired invitations."""
   totalCount: Int!
 }
 ```
@@ -365,25 +344,19 @@ type OrganizationInvitationConnection {
 
 ```graphql
 """
-An invitation addressed to the authenticated viewer, exposed via
-`User.invitations`. Carries the organisation name (so the dashboard can
-render a "Join <Org>" CTA without an extra fetch) plus the `token` the
-client passes to `organizationInvitationAccept` /
-`organizationInvitationDecline`.
-
-WARNING: `token` is sensitive — it grants the bearer the right to join
-the organisation. Treat it like a one-time secret.
+An invitation addressed to the viewer's email address. Its `token` lets the bearer join the
+organisation, so treat it as a secret.
 """
 type ViewerInvitation {
-  """Unique invitation identifier."""
+  """The ID of the invitation."""
   id: ID!
-  """Token used to accept or decline the invitation. Treat as sensitive."""
+  """The token that accepts or declines the invitation."""
   token: String!
-  """Name of the inviting organisation."""
+  """The name of the inviting organisation."""
   organizationName: String!
-  """When this invitation was created."""
+  """When the invitation was created."""
   createdAt: DateTime!
-  """When this invitation expires."""
+  """When the invitation expires."""
   expiresAt: DateTime!
 }
 ```
@@ -391,11 +364,11 @@ type ViewerInvitation {
 ### `ViewerInvitationEdge`
 
 ```graphql
-"""Edge type for `ViewerInvitationConnection`."""
+"""An invitation in a page of results."""
 type ViewerInvitationEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
-  """The viewer invitation."""
+  """The invitation."""
   node: ViewerInvitation!
 }
 ```
@@ -403,13 +376,13 @@ type ViewerInvitationEdge {
 ### `ViewerInvitationConnection`
 
 ```graphql
-"""Relay-style connection of the viewer's pending invitations."""
+"""A page of the viewer's invitations."""
 type ViewerInvitationConnection {
-  """List of invitation edges."""
+  """The edges in this page."""
   edges: [ViewerInvitationEdge!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of invitations."""
+  """The total number of invitations."""
   totalCount: Int!
 }
 ```
@@ -417,9 +390,9 @@ type ViewerInvitationConnection {
 ### `OrganizationEdge`
 
 ```graphql
-"""Edge type for `OrganizationConnection`."""
+"""An organisation in a page of results."""
 type OrganizationEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The organisation."""
   node: Organization!
@@ -429,13 +402,13 @@ type OrganizationEdge {
 ### `OrganizationConnection`
 
 ```graphql
-"""Relay-style connection of organisations."""
+"""A page of organisations."""
 type OrganizationConnection {
-  """List of organisation edges."""
+  """The edges in this page."""
   edges: [OrganizationEdge!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of organisations."""
+  """The total number of organisations."""
   totalCount: Int!
 }
 ```
@@ -444,12 +417,12 @@ type OrganizationConnection {
 
 ```graphql
 """
-Input for looking up a single organisation. Provide either `id` or `slug` — at least one is required.
+The input of `organization`. Give `id` or `slug`; `id` wins when both are given.
 """
 input OrganizationInput {
-  """Organisation ID to look up."""
+  """The ID of the organisation."""
   id: ID
-  """Organisation slug to look up."""
+  """The slug of the organisation."""
   slug: String
 }
 ```
@@ -457,12 +430,13 @@ input OrganizationInput {
 ### `OrganizationCreateInput`
 
 ```graphql
-"""Input for `organizationCreate`."""
+"""The input of `organizationCreate`."""
 input OrganizationCreateInput {
-  """Name of the organisation."""
+  """The name of the organisation."""
   name: String!
   """
-  URL-friendly slug for the organisation. Must be unique across all organisations.
+  The slug of the organisation: lowercase letters, numbers and hyphens, unique across Picked. A
+  few words that name dashboard pages, such as `account` and `login`, are reserved.
   """
   slug: String!
 }
@@ -471,9 +445,9 @@ input OrganizationCreateInput {
 ### `OrganizationCreatePayload`
 
 ```graphql
-"""Payload returned by `organizationCreate`."""
+"""The result of `organizationCreate`."""
 type OrganizationCreatePayload {
-  """The newly created organisation."""
+  """The created organisation."""
   organization: Organization
 }
 ```
@@ -481,18 +455,17 @@ type OrganizationCreatePayload {
 ### `OrganizationUpdateInput`
 
 ```graphql
-"""Input for `organizationUpdate`."""
+"""The input of `organizationUpdate`. Omit a field to keep its value."""
 input OrganizationUpdateInput {
-  """ID of the organisation to update."""
+  """The ID of the organisation."""
   id: ID!
-  """New name for the organisation. Omit to keep the existing value."""
+  """The name of the organisation."""
   name: String
-  """New slug for the organisation. Must remain unique."""
+  """The slug of the organisation, under the same rules as on create."""
   slug: String
   """
-  Whether every member must hold an `AAL2` session. Setting it to true needs
-  the caller's own session at `AAL2` (an `AAL1` or OAuth-client token is
-  refused with `MFA_REQUIRED`) and revokes every member's OAuth-client sessions.
+  Whether every member must hold an `AAL2` session. Turning it on needs the caller's own session
+  at `AAL2`, else fails with `MFA_REQUIRED`, and signs every member out of their OAuth clients.
   """
   requireMfa: Boolean
 }
@@ -501,7 +474,7 @@ input OrganizationUpdateInput {
 ### `OrganizationUpdatePayload`
 
 ```graphql
-"""Payload returned by `organizationUpdate`."""
+"""The result of `organizationUpdate`."""
 type OrganizationUpdatePayload {
   """The updated organisation."""
   organization: Organization
@@ -511,9 +484,9 @@ type OrganizationUpdatePayload {
 ### `OrganizationDeleteInput`
 
 ```graphql
-"""Input for `organizationDelete`."""
+"""The input of `organizationDelete`."""
 input OrganizationDeleteInput {
-  """ID of the organisation to delete."""
+  """The ID of the organisation."""
   id: ID!
 }
 ```
@@ -521,9 +494,9 @@ input OrganizationDeleteInput {
 ### `OrganizationDeletePayload`
 
 ```graphql
-"""Payload returned by `organizationDelete`."""
+"""The result of `organizationDelete`."""
 type OrganizationDeletePayload {
-  """ID of the deleted organisation."""
+  """The ID of the deleted organisation."""
   deletedOrganizationId: ID
 }
 ```
@@ -531,23 +504,20 @@ type OrganizationDeletePayload {
 ### `OrganizationMemberInviteInput`
 
 ```graphql
-"""
-Input for `organizationMemberInvite` — create a pending invitation for the given email.
-"""
+"""The input of `organizationMemberInvite`."""
 input OrganizationMemberInviteInput {
-  """ID of the organisation to invite the member to."""
+  """The ID of the organisation."""
   organizationId: ID!
-  """Email address of the user to invite."""
+  """The email address to invite."""
   email: String!
   """
-  Scopes the invitation grants on acceptance, one entry per location. Omit to
-  grant the preset matching `role`. The inviter may not grant a scope they do
-  not themselves hold.
+  The scopes the invitation grants on acceptance, one entry per location. Omit to grant
+  `ORGANIZATION_READ` alone. The inviter cannot grant a scope they do not hold.
   """
   grants: [MemberScopeGrantInput!]
-  """Invitation type. Ignored; retained for backwards compatibility."""
+  """Ignored."""
   invitationType: InvitationType @deprecated(reason: "All invitations are now single-use. This field is ignored.")
-  """URL to redirect the invited user to after email verification."""
+  """The URL the email's link returns the invitee to."""
   redirectUrl: String
 }
 ```
@@ -560,12 +530,12 @@ enum InvitationDelivery {
   """An invitation email, for an address with no account."""
   INVITE_EMAIL
   """
-  A sign-in email, for an address that already has an account. The invitation
-  waits on the user's Account page.
+  A sign-in email, for an address that already has an account. The invitation waits on the
+  user's Account page.
   """
   SIGN_IN_EMAIL
   """
-  No email went out. The invitation still waits on the Account page of a user with the address.
+  No email. The invitation still waits on the Account page of a user with the address.
   """
   NOT_SENT
 }
@@ -574,7 +544,7 @@ enum InvitationDelivery {
 ### `OrganizationMemberInvitePayload`
 
 ```graphql
-"""Payload returned by `organizationMemberInvite`."""
+"""The result of `organizationMemberInvite`."""
 type OrganizationMemberInvitePayload {
   """The created invitation."""
   invitation: OrganizationInvitation
@@ -586,9 +556,11 @@ type OrganizationMemberInvitePayload {
 ### `OrganizationInvitationAcceptInput`
 
 ```graphql
-"""Input for `organizationInvitationAccept`."""
+"""The input of `organizationInvitationAccept`."""
 input OrganizationInvitationAcceptInput {
-  """Token from the invitation email — see `ViewerInvitation.token`."""
+  """
+  The token of the invitation, from `ViewerInvitation.token` or the invitation email.
+  """
   token: String!
 }
 ```
@@ -596,11 +568,11 @@ input OrganizationInvitationAcceptInput {
 ### `AcceptedMembership`
 
 ```graphql
-"""Membership information returned after accepting an invitation."""
+"""The organisation a user joined by accepting an invitation."""
 type AcceptedMembership {
-  """ID of the organisation joined."""
+  """The ID of the organisation."""
   organizationId: ID!
-  """Name of the organisation joined."""
+  """The name of the organisation."""
   organizationName: String!
 }
 ```
@@ -608,9 +580,9 @@ type AcceptedMembership {
 ### `OrganizationInvitationAcceptPayload`
 
 ```graphql
-"""Payload returned by `organizationInvitationAccept`."""
+"""The result of `organizationInvitationAccept`."""
 type OrganizationInvitationAcceptPayload {
-  """The membership created by accepting the invitation."""
+  """The organisation joined."""
   membership: AcceptedMembership
 }
 ```
@@ -618,9 +590,9 @@ type OrganizationInvitationAcceptPayload {
 ### `OrganizationInvitationDeclineInput`
 
 ```graphql
-"""Input for `organizationInvitationDecline`."""
+"""The input of `organizationInvitationDecline`."""
 input OrganizationInvitationDeclineInput {
-  """Token from the invitation email."""
+  """The token of the invitation."""
   token: String!
 }
 ```
@@ -628,9 +600,9 @@ input OrganizationInvitationDeclineInput {
 ### `OrganizationInvitationDeclinePayload`
 
 ```graphql
-"""Payload returned by `organizationInvitationDecline`."""
+"""The result of `organizationInvitationDecline`."""
 type OrganizationInvitationDeclinePayload {
-  """Token of the declined invitation."""
+  """The token of the declined invitation."""
   declinedToken: String
 }
 ```
@@ -638,13 +610,11 @@ type OrganizationInvitationDeclinePayload {
 ### `OrganizationInvitationRevokeInput`
 
 ```graphql
-"""
-Input for `organizationInvitationRevoke` — withdraw a pending invitation.
-"""
+"""The input of `organizationInvitationRevoke`."""
 input OrganizationInvitationRevokeInput {
-  """ID of the invitation to revoke."""
+  """The ID of the invitation."""
   invitationId: ID!
-  """ID of the organisation the invitation belongs to."""
+  """Ignored. The invitation's own organisation applies."""
   organizationId: ID!
 }
 ```
@@ -652,9 +622,9 @@ input OrganizationInvitationRevokeInput {
 ### `OrganizationInvitationRevokePayload`
 
 ```graphql
-"""Payload returned by `organizationInvitationRevoke`."""
+"""The result of `organizationInvitationRevoke`."""
 type OrganizationInvitationRevokePayload {
-  """ID of the revoked invitation."""
+  """The ID of the revoked invitation."""
   revokedInvitationId: ID
 }
 ```
@@ -662,11 +632,11 @@ type OrganizationInvitationRevokePayload {
 ### `OrganizationMemberRemoveInput`
 
 ```graphql
-"""Input for `organizationMemberRemove`."""
+"""The input of `organizationMemberRemove`."""
 input OrganizationMemberRemoveInput {
-  """ID of the organisation to remove the member from."""
+  """The ID of the organisation."""
   organizationId: ID!
-  """ID of the user to remove."""
+  """The ID of the member's user."""
   userId: ID!
 }
 ```
@@ -674,9 +644,9 @@ input OrganizationMemberRemoveInput {
 ### `OrganizationMemberRemovePayload`
 
 ```graphql
-"""Payload returned by `organizationMemberRemove`."""
+"""The result of `organizationMemberRemove`."""
 type OrganizationMemberRemovePayload {
-  """ID of the removed user."""
+  """The ID of the removed member's user."""
   removedUserId: ID
 }
 ```
@@ -684,11 +654,16 @@ type OrganizationMemberRemovePayload {
 ### `MemberScopeGrantInput`
 
 ```graphql
-"""A set of scopes to grant at one location within an organisation."""
+"""
+The scopes to grant at one location in an organisation. A grant on the organisation itself
+always includes `ORGANIZATION_READ`.
+"""
 input MemberScopeGrantInput {
-  """The project the scopes apply to, or null for the organisation itself."""
+  """
+  The ID of the project the scopes apply to. Null for the organisation itself.
+  """
   projectId: ID
-  """The scopes to hold at that location."""
+  """The scopes to hold at the location."""
   scopes: [Scope!]!
 }
 ```
@@ -696,15 +671,17 @@ input MemberScopeGrantInput {
 ### `OrganizationMemberScopesUpdateInput`
 
 ```graphql
-"""Input for `organizationMemberScopesUpdate`."""
+"""
+The input of `organizationMemberScopesUpdate`. Every field is required.
+"""
 input OrganizationMemberScopesUpdateInput {
-  """ID of the organisation."""
+  """The ID of the organisation."""
   organizationId: ID!
-  """ID of the member whose scopes to set."""
+  """The ID of the member's user."""
   userId: ID!
   """
-  The grants to leave in place. Locations absent from this list are cleared;
-  grants outside this organisation are untouched.
+  Every grant the member keeps in the organisation, at most one per location. A location left
+  out loses its grant. `ORGANIZATION_MEMBERS_MANAGE_SCOPES` applies to the organisation only.
   """
   grants: [MemberScopeGrantInput!]!
 }
@@ -713,7 +690,7 @@ input OrganizationMemberScopesUpdateInput {
 ### `OrganizationMemberScopesUpdatePayload`
 
 ```graphql
-"""Payload returned by `organizationMemberScopesUpdate`."""
+"""The result of `organizationMemberScopesUpdate`."""
 type OrganizationMemberScopesUpdatePayload {
   """The member whose scopes were set."""
   member: OrganizationMember
@@ -723,16 +700,17 @@ type OrganizationMemberScopesUpdatePayload {
 ### `OrganizationClientManagerScopesUpdateInput`
 
 ```graphql
-"""Input for `organizationClientManagerScopesUpdate`."""
+"""
+The input of `organizationClientManagerScopesUpdate`. Every field is required.
+"""
 input OrganizationClientManagerScopesUpdateInput {
-  """ID of the organisation."""
+  """The ID of the organisation."""
   organizationId: ID!
-  """ID of the client manager whose scopes to set."""
+  """The ID of the client manager's user."""
   userId: ID!
   """
-  The scopes to hold on this organisation, replacing whatever was held before.
-  An empty list clears the grant, leaving the root grant as their whole reach.
-  Root-located scopes are rejected: they bind to no organisation.
+  The scopes to hold in the organisation, replacing the current ones. An empty list clears them,
+  leaving the root grant. A scope that applies to every organisation fails validation.
   """
   scopes: [Scope!]!
 }
@@ -741,9 +719,9 @@ input OrganizationClientManagerScopesUpdateInput {
 ### `OrganizationClientManagerScopesUpdatePayload`
 
 ```graphql
-"""Payload returned by `organizationClientManagerScopesUpdate`."""
+"""The result of `organizationClientManagerScopesUpdate`."""
 type OrganizationClientManagerScopesUpdatePayload {
-  """The client manager whose scopes were set."""
+  """The client manager and the scopes they now hold."""
   access: OrganizationClientManagerAccess
 }
 ```