picked 0.0.101 → 0.0.102-next.2

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

@@ -6,13 +6,13 @@ generated: true
 
 # Common schema
 
-The operations and types that `common.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
 
 ### `ping`
 
-Liveness probe used by infrastructure to confirm the GraphQL endpoint is up. Unauthenticated.
+Checks that the API is up. Answers `pong`.
 
 ```graphql
 ping: String!
@@ -24,12 +24,8 @@ ping: String!
 
 ```graphql
 """
-Arbitrary JSON value. Encoded as a JSON document; decoded as a JavaScript
-value (object, array, number, string, boolean, or null).
-
-Used as an escape hatch when the underlying shape is dynamic (workspace
-flow graphs, condition logic, validation rules, project settings, CMS
-field values). When a typed alternative exists, prefer that.
+Any JSON value: an object, an array, a number, a string, a boolean or null. Carries data whose
+shape varies, such as flow graphs, condition logic and content entry values.
 """
 scalar JSON
 ```
@@ -38,9 +34,7 @@ scalar JSON
 
 ```graphql
 """
-ISO 8601 date-time string in UTC, e.g. `2026-05-14T08:30:00.000Z`. Always
-encoded with millisecond precision and a `Z` suffix; the server never
-emits a local offset.
+A date-time in UTC with millisecond precision, such as `2026-05-14T08:30:00.000Z`.
 """
 scalar DateTime
 ```
@@ -49,10 +43,8 @@ scalar DateTime
 
 ```graphql
 """
-ISO 8601 date (`YYYY-MM-DD`) or date-time value used by CMS `DATE` fields.
-Unlike `DateTime`, a bare date without a time component is accepted, matching
-a `DATE` field whose `includeTime` flag is `false`. Values are round-tripped
-verbatim, so a date-only field never gains a spurious time-of-day.
+An ISO 8601 date (`YYYY-MM-DD`) or date-time, as a content entry's `DATE` field holds it. The
+value comes back exactly as it was written, so a date never gains a time of day.
 """
 scalar IsoDate
 ```
@@ -60,15 +52,11 @@ scalar IsoDate
 ### `AuthType`
 
 ```graphql
-"""
-Restricts which authentication kind is accepted by an `@auth` directive.
-Most fields accept either credential; pass `only` to lock a field down to
-one transport.
-"""
+"""The kind of credential an `@auth` field accepts."""
 enum AuthType {
-  """A Supabase JWT (the `Authorization: Bearer <token>` header)."""
+  """A user access token, sent as `Authorization: Bearer <token>`."""
   USER
-  """An API key (the `X-API-Key` header)."""
+  """An API key, sent as `X-API-Key`."""
   API_KEY
 }
 ```
@@ -77,18 +65,14 @@ enum AuthType {
 
 ```graphql
 """
-Whether a field holds a signed-in user to the multi-factor authentication
-policy. Every `@auth` field enforces it unless it says otherwise.
+Whether an `@auth` field holds a user to the two-factor authentication policy.
 """
 enum AuthMfaPolicy {
   """
-  Refuse a user who must hold a verified second factor and whose session is `AAL1` with `MFA_REQUIRED`.
+  Refuse a user who owes a second factor with `MFA_REQUIRED` until their session is `AAL2`.
   """
   ENFORCE
-  """
-  Serve the field at `AAL1`. Reserved for what a user needs to reach `AAL2` (`user` and
-  the MFA mutations) and for `passwordUpdate`, which checks the caller's factors itself.
-  """
+  """Serve the field to a user whose session is `AAL1`."""
   EXEMPT
 }
 ```
@@ -97,22 +81,17 @@ enum AuthMfaPolicy {
 
 ```graphql
 """
-Authenticates the request using a Supabase JWT (`USER`) or an API key
-(`API_KEY`). By default, both auth types are accepted; use `only` to
-restrict to a specific type.
-
-Throws `UNAUTHENTICATED` if no credential is present, the credential is
-malformed, or the credential's type is not allowed by `only`.
+Authenticates the request before the field resolves. A request carries a user access token
+(`Authorization: Bearer <token>`) or an API key (`X-API-Key`).
 
-A user session is then held to the multi-factor authentication policy: a
-super admin, a client manager, or a member of an organisation that requires
-two-factor authentication is refused with `MFA_REQUIRED` when the session is
-`AAL1`, unless the field is `mfa: EXEMPT`. Tokens minted by the OAuth 2.1
-server satisfy the policy, because consent is only given from an `AAL2`
-session. API keys are never evaluated.
+Without `only`, the field accepts either credential. `only: USER` accepts a user access token and
+refuses an API key. `only: API_KEY` accepts an API key and refuses a user access token. A missing,
+invalid or refused credential fails with `UNAUTHENTICATED`.
 
-The auth result is memoised per-request, so multiple `@auth` fields in
-the same operation share a single verify call.
+`mfa` applies to user access tokens only. With `mfa: ENFORCE`, the default, a super admin, a client
+manager or a member of an organisation that requires two-factor authentication is refused with
+`MFA_REQUIRED` while their session is `AAL1`; a token issued through OAuth counts as `AAL2`.
+`mfa: EXEMPT` serves the field at `AAL1`, so such a user can enrol or verify a second factor.
 """
 directive @auth(only: AuthType, mfa: AuthMfaPolicy = ENFORCE) on FIELD_DEFINITION
 ```
@@ -121,21 +100,8 @@ directive @auth(only: AuthType, mfa: AuthMfaPolicy = ENFORCE) on FIELD_DEFINITIO
 
 ```graphql
 """
-HTTP `Cache-Control` policy applied to a field's response. The directive
-stores the policy on the GraphQL context during field resolution; a yoga
-plugin reads it and emits a `Cache-Control` response header. Responses
-that contain GraphQL errors never receive the header.
-
-WARNING: `@cache` MUST NOT be selected in the same operation as any `@auth`
-field. The cache header attaches to the entire response, so a public
-`Cache-Control` on a payload containing authenticated data leaks that data
-to shared caches. This is enforced by convention only — there is no
-runtime check. Keep cached fields in their own operations.
-
-WARNING: `policy` is opaque. Whatever string is passed is emitted verbatim
-as `Cache-Control`; there is no runtime validation. Use a hardcoded
-literal (e.g. `policy: "public, max-age=300"`). NEVER derive `policy` from
-user input.
+Sets the response's HTTP `Cache-Control` header to `policy`, verbatim. A response that has errors,
+or in which an `@auth` field ran, gets no header.
 """
 directive @cache(policy: String!) on FIELD_DEFINITION
 ```
@@ -144,21 +110,15 @@ directive @cache(policy: String!) on FIELD_DEFINITION
 
 ```graphql
 """
-Authorisation scopes following the `{entity}/{action}` convention. Used
-for fine-grained access control at the entity level — the dashboard and
-the SDKs both check scopes via `Organization.viewerScopes` and the
-authenticated user's root-level `viewerScopes`.
-
-Scopes prefixed with `ORGANIZATION_` are organisation-scoped (granted via
-an organisation membership). Scopes prefixed with `STAFF_` and `FLAGS_`
-are system-level (granted via the staff role on the user record).
+A permission that an operation checks. `ORGANIZATION_` scopes come from an organisation membership
+or an API key. `STAFF_`, `FLAGS_` and `USERS_` scopes are system-level and held by Picked staff.
 """
 enum Scope {
   """Create new organisations."""
   ORGANIZATION_CREATE
   """Read organisation details."""
   ORGANIZATION_READ
-  """Update organisation settings (name, slug)."""
+  """Update organisation settings."""
   ORGANIZATION_UPDATE
   """Delete an organisation."""
   ORGANIZATION_DELETE
@@ -226,25 +186,25 @@ enum Scope {
   ORGANIZATION_ACTION_RUNS_UPDATE
   """Call an external API registered to the project."""
   ORGANIZATION_EXTERNAL_APIS_CALL
-  """View staff-level data (system-level, not organisation-scoped)."""
+  """View staff-level data."""
   STAFF_READ
-  """Invite admin users (system-level)."""
+  """Invite super admins."""
   STAFF_INVITE_ADMIN
-  """Invite client managers (system-level)."""
+  """Invite client managers."""
   STAFF_INVITE_CLIENT_MANAGER
-  """Create feature flags (system-level)."""
+  """Create platform feature flags."""
   FLAGS_CREATE
-  """Update feature flags (system-level)."""
+  """Update platform feature flags."""
   FLAGS_UPDATE
-  """Delete feature flags (system-level)."""
+  """Delete platform feature flags."""
   FLAGS_DELETE
   """
-  Reset a user's two-factor authentication: delete their factors and revoke their sessions (system-level, super admins only).
+  Reset a user's two-factor authentication: delete their factors and revoke their sessions.
   """
   USERS_RESET_MFA
-  """Read live workspace versions (preview tokens, organisation members)."""
+  """Read a workspace's preview configuration."""
   ORGANIZATION_WORKSPACE_VERSION_READ
-  """Read published workspace versions (anonymous public access)."""
+  """Read what a project serves to visitors, and run its actions."""
   ORGANIZATION_WORKSPACE_VERSION_READ_PUBLIC
 }
 ```
@@ -253,59 +213,49 @@ enum Scope {
 
 ```graphql
 """
-General-purpose error codes returned in the standard GraphQL `errors`
-array's `extensions.code`. Auth-specific codes live on `AuthErrorCode` —
-this enum covers the rest of the API (organisations, projects, members,
-invitations, validation, internal errors).
-
-Each code maps to an HTTP status code in the response envelope. Use
-this enum when handling errors programmatically; do not parse the
-human-readable `message`.
+The codes an entry in the GraphQL `errors` array carries in `extensions.code`. Branch on the code,
+not on `message`.
 """
 enum ErrorCode {
-  """The provided credentials are invalid."""
+  """The credentials are invalid."""
   INVALID_CREDENTIALS
-  """The request is not authorised (the caller is unauthenticated)."""
+  """The operation needs a signed-in user."""
   UNAUTHORIZED
-  """
-  The request is forbidden (the caller is authenticated but lacks scope).
-  """
+  """The caller is authenticated but lacks the scope."""
   FORBIDDEN
-  """The specified organisation was not found."""
+  """The organisation does not exist."""
   ORGANIZATION_NOT_FOUND
-  """An organisation with the provided name already exists."""
+  """An organisation with this name already exists."""
   ORGANIZATION_ALREADY_EXISTS
-  """The provided slug is already in use."""
+  """The slug is already in use."""
   SLUG_ALREADY_EXISTS
   """
-  The provided slug is invalid (allowed: lowercase letters, digits, hyphens).
+  The slug holds characters other than lowercase letters, digits and hyphens.
   """
   INVALID_SLUG
-  """The specified member was not found."""
+  """The member does not exist."""
   MEMBER_NOT_FOUND
-  """The user is already a member of this organisation."""
+  """The user is already a member of the organisation."""
   MEMBER_ALREADY_EXISTS
   """The primary owner cannot be removed from the organisation."""
   CANNOT_REMOVE_PRIMARY_OWNER
-  """The specified invitation was not found."""
+  """The invitation does not exist."""
   INVITATION_NOT_FOUND
   """The invitation has expired."""
   INVITATION_EXPIRED
   """The invitation has already been accepted."""
   INVITATION_ALREADY_ACCEPTED
-  """The specified project was not found."""
+  """The project does not exist."""
   PROJECT_NOT_FOUND
-  """The specified user was not found."""
+  """The user does not exist."""
   USER_NOT_FOUND
-  """The role has already been granted to this user."""
+  """The user already holds the role."""
   ROLE_ALREADY_GRANTED
-  """The role has not been granted to this user."""
+  """The user does not hold the role."""
   ROLE_NOT_GRANTED
-  """
-  A validation error occurred. Inspect `extensions.fields` for affected paths.
-  """
+  """The input is invalid. `extensions.fields` names the paths at fault."""
   VALIDATION_ERROR
-  """An internal server error occurred."""
+  """An unexpected server error."""
   INTERNAL_ERROR
 }
 ```
@@ -314,22 +264,19 @@ enum ErrorCode {
 
 ```graphql
 """
-Relay-style page metadata returned by every cursor-paginated `*Connection`
-type. Cursors are opaque, base64-encoded strings; treat them as opaque
-identifiers and do not parse or modify them.
-
-When `hasNextPage` is true, pass `endCursor` as the next `after` argument
-to fetch the next page. When `hasPreviousPage` is true and the connection
-supports backward pagination, pass `startCursor` as `before`.
+Where a page sits in a list. Cursors are opaque: pass `endCursor` as `after` to read the next
+page, and `startCursor` as `before` to read the previous one.
 """
 type PageInfo {
-  """Whether there are more items after the last edge in this page."""
+  """Whether items follow this page."""
   hasNextPage: Boolean!
-  """Whether there are more items before the first edge in this page."""
+  """Whether items precede this page."""
   hasPreviousPage: Boolean!
-  """Cursor of the first edge in the page (null if the page is empty)."""
+  """
+  The cursor of the first item in this page. Null when the page is empty.
+  """
   startCursor: String
-  """Cursor of the last edge in the page (null if the page is empty)."""
+  """The cursor of the last item in this page. Null when the page is empty."""
   endCursor: String
 }
 ```
@@ -338,25 +285,17 @@ type PageInfo {
 
 ```graphql
 """
-A user-facing validation error attached to a mutation payload's
-`userErrors` array. Distinct from thrown domain errors (which surface in
-the standard GraphQL `errors` array): `userErrors` represent business-
-logic constraints the client should surface to the user, often with
-structured context.
-
-`field` is a dotted path into the operation's input; `code` is the
-machine-readable error code (mutation-specific, defined alongside the
-payload); `message` is human-readable and should be shown to the user.
-
-Some mutations return a typed subclass of `UserError` (e.g.
-`ActionDeleteUserError`) with extra fields like `referencingExperiences`.
+A problem with a mutation's input that stopped the mutation, returned in its payload's
+`userErrors`. Some mutations return their own error type with a typed `code`.
 """
 type UserError {
-  """Path to the field that caused the error."""
+  """
+  The path to the input field at fault. Null when no single field is at fault.
+  """
   field: [String!]
-  """Human-readable error message."""
+  """A message to show the user."""
   message: String!
-  """Machine-readable error code."""
+  """A machine-readable code. Null when the mutation defines none."""
   code: String
 }
 ```

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

@@ -6,13 +6,14 @@ generated: true
 
 # Condition schema
 
-The operations and types that `condition.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
 
 ### `condition`
 
-Get a condition by ID within a workspace.
+Reads a condition.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 condition(id: ID!, workspaceId: ID!): Condition @auth
@@ -20,8 +21,9 @@ condition(id: ID!, workspaceId: ID!): Condition @auth
 
 ### `conditions`
 
-List conditions in a workspace. Filter by name with `search` (case-insensitive
-substring) and order with `sortKey` (default `NAME`) plus `reverse`.
+Lists the conditions in a workspace. `search` matches a case-insensitive substring of the name;
+`sortKey` and `reverse` set the order.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 conditions(first: Int, after: String, last: Int, before: String, workspaceId: ID!, search: String, sortKey: ConditionSortKeys = NAME, reverse: Boolean = false): ConditionConnection! @auth
@@ -31,7 +33,8 @@ conditions(first: Int, after: String, last: Int, before: String, workspaceId: ID
 
 ### `conditionCreate`
 
-Create a new condition. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Creates a condition in a workspace.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 conditionCreate(input: ConditionCreateInput!): ConditionCreatePayload! @auth
@@ -39,7 +42,8 @@ conditionCreate(input: ConditionCreateInput!): ConditionCreatePayload! @auth
 
 ### `conditionUpdate`
 
-Update a condition. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Updates a condition.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 conditionUpdate(input: ConditionUpdateInput!): ConditionUpdatePayload! @auth
@@ -47,7 +51,9 @@ conditionUpdate(input: ConditionUpdateInput!): ConditionUpdatePayload! @auth
 
 ### `conditionDelete`
 
-Delete a condition. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Deletes a condition. A condition that an experience or another condition references is not
+deleted, and comes back as an `IN_USE` user error.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 conditionDelete(input: ConditionDeleteInput!): ConditionDeletePayload! @auth
@@ -59,33 +65,24 @@ conditionDelete(input: ConditionDeleteInput!): ConditionDeletePayload! @auth
 
 ```graphql
 """
-Branching logic in an experience flow. The condition is evaluated by the
-SDK using the JSON-Logic format; `logic` is the AST.
-
-When attached to a `ConditionNode`, the result selects which outgoing
-edge (`sourceHandle: TRUE` / `FALSE`) the flow follows.
+A rule that decides whether a visitor sees something, or which branch a flow takes.
 """
 type Condition {
-  """Unique condition identifier."""
+  """The ID of the condition."""
   id: ID!
-  """Display name of the condition."""
+  """The name of the condition."""
   name: String!
-  """Stable, human-readable key for SDK consumers."""
+  """The stable identifier of the condition, unique within its workspace."""
   key: String!
-  """
-  JSON Logic expression. See https://jsonlogic.com for the grammar — the
-  shape is a recursive tagged-tree e.g. `{ "and": [{ "==": [{ "var": "country" }, "US"] }, ...] }`.
-  """
+  """The rule, as a JSON Logic expression (https://jsonlogic.com)."""
   logic: JSON!
-  """When this condition was created."""
+  """When the condition was created."""
   createdAt: DateTime!
-  """When this condition was last updated."""
+  """When the condition last changed."""
   updatedAt: DateTime!
-  """The workspace this condition belongs to."""
+  """The workspace the condition belongs to."""
   workspace: Workspace!
-  """
-  The workspace ID this condition belongs to (denormalised for query convenience).
-  """
+  """The ID of the workspace the condition belongs to."""
   workspaceId: ID
 }
 ```
@@ -93,19 +90,15 @@ type Condition {
 ### `ConditionConnection`
 
 ```graphql
-"""
-Relay-style connection of conditions, with both an `edges` list and a flat `nodes` accessor.
-"""
+"""A page of conditions."""
 type ConditionConnection {
-  """List of condition edges."""
+  """The edges in this page."""
   edges: [ConditionEdge!]!
-  """
-  Flat list of conditions, equivalent to `edges[].node`. Convenience accessor.
-  """
+  """The conditions in this page."""
   nodes: [Condition!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of conditions."""
+  """The number of conditions across all pages, ignoring `search`."""
   totalCount: Int!
 }
 ```
@@ -113,9 +106,9 @@ type ConditionConnection {
 ### `ConditionEdge`
 
 ```graphql
-"""Edge type for `ConditionConnection`."""
+"""A condition in a page of results."""
 type ConditionEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The condition."""
   node: Condition!
@@ -125,16 +118,19 @@ type ConditionEdge {
 ### `ConditionCreateInput`
 
 ```graphql
-"""Input for `conditionCreate`."""
+"""The input of `conditionCreate`."""
 input ConditionCreateInput {
-  """Workspace ID to create the condition in."""
+  """The ID of the workspace to create the condition in."""
   workspaceId: ID!
-  """Display name for the condition."""
+  """The name of the condition."""
   name: String!
-  """Unique key identifier for the condition."""
+  """
+  The stable identifier of the condition, unique within the workspace. It cannot change later.
+  """
   key: String!
   """
-  JSON Logic expression string for condition evaluation. Server parses and validates the JSON before persisting.
+  The rule, as a JSON Logic expression in a JSON string. It can call another condition with
+  `{ "invoke": [{ "var": "conditions.<key>" }] }`; an unknown key or a cycle is rejected.
   """
   logicString: String!
 }
@@ -143,7 +139,7 @@ input ConditionCreateInput {
 ### `ConditionCreatePayload`
 
 ```graphql
-"""Payload returned by `conditionCreate`."""
+"""The result of `conditionCreate`."""
 type ConditionCreatePayload {
   """The created condition."""
   condition: Condition
@@ -153,16 +149,16 @@ type ConditionCreatePayload {
 ### `ConditionUpdateInput`
 
 ```graphql
-"""Input for `conditionUpdate`. Omit a field to leave it unchanged."""
+"""The input of `conditionUpdate`. Omit a field to keep its value."""
 input ConditionUpdateInput {
-  """Condition ID."""
+  """The ID of the condition."""
   id: ID!
-  """Workspace ID the condition belongs to."""
+  """The ID of the workspace the condition belongs to."""
   workspaceId: ID!
-  """New display name."""
+  """The name of the condition."""
   name: String
   """
-  New JSON Logic expression string. Server parses and validates the JSON before persisting.
+  The rule, as a JSON Logic expression in a JSON string. An unknown condition key or a cycle is rejected.
   """
   logicString: String
 }
@@ -171,7 +167,7 @@ input ConditionUpdateInput {
 ### `ConditionUpdatePayload`
 
 ```graphql
-"""Payload returned by `conditionUpdate`."""
+"""The result of `conditionUpdate`."""
 type ConditionUpdatePayload {
   """The updated condition."""
   condition: Condition
@@ -181,11 +177,11 @@ type ConditionUpdatePayload {
 ### `ConditionDeleteInput`
 
 ```graphql
-"""Input for `conditionDelete`."""
+"""The input of `conditionDelete`."""
 input ConditionDeleteInput {
-  """Condition ID."""
+  """The ID of the condition."""
   id: ID!
-  """Workspace ID the condition belongs to."""
+  """The ID of the workspace the condition belongs to."""
   workspaceId: ID!
 }
 ```
@@ -193,13 +189,11 @@ input ConditionDeleteInput {
 ### `ConditionDeletePayload`
 
 ```graphql
-"""
-Payload returned by `conditionDelete`. Returns `userErrors` when the condition is in use.
-"""
+"""The result of `conditionDelete`."""
 type ConditionDeletePayload {
-  """ID of the deleted condition (null when `userErrors` is non-empty)."""
+  """The ID of the deleted condition. Null when `userErrors` is not empty."""
   deletedConditionId: ID
-  """Validation errors. Empty array indicates success."""
+  """The reasons the condition was not deleted. Empty on success."""
   userErrors: [ConditionDeleteUserError!]!
 }
 ```
@@ -207,11 +201,9 @@ type ConditionDeletePayload {
 ### `ConditionDeleteUserErrorCode`
 
 ```graphql
-"""Machine-readable error codes for `conditionDelete`."""
+"""The reasons `conditionDelete` refuses a delete."""
 enum ConditionDeleteUserErrorCode {
-  """
-  The condition is referenced by one or more experiences and cannot be deleted.
-  """
+  """An experience or another condition references the condition."""
   IN_USE
 }
 ```
@@ -219,18 +211,18 @@ enum ConditionDeleteUserErrorCode {
 ### `ConditionDeleteUserError`
 
 ```graphql
-"""
-A user error from `conditionDelete`. Carries the experiences that block the delete when `code` is `IN_USE`.
-"""
+"""A reason `conditionDelete` did not delete a condition."""
 type ConditionDeleteUserError {
-  """Path to the input field that caused the error."""
+  """
+  The path to the input field at fault. Null when no single field is at fault.
+  """
   field: [String!]
-  """Human-readable error message."""
+  """A message to show the user."""
   message: String!
-  """Machine-readable error code."""
+  """A machine-readable code."""
   code: ConditionDeleteUserErrorCode!
   """
-  Experiences that reference this condition (present when `code` is `IN_USE`).
+  The experiences that reference the condition. Null unless `code` is `IN_USE`.
   """
   referencingExperiences: [ReferencingExperience!]
 }
@@ -239,16 +231,13 @@ type ConditionDeleteUserError {
 ### `ConditionSortKeys`
 
 ```graphql
-"""
-Sort keys for `conditions(...)`. Pair with `reverse: true` to flip the order
-(`NAME` + `reverse: false` sorts A→Z; `CREATED_AT` + `reverse: true` is newest-first).
-"""
+"""The orders `conditions` can sort by. `reverse: true` flips each."""
 enum ConditionSortKeys {
-  """Sort by `name` (alphabetical)."""
+  """By name, A to Z."""
   NAME
-  """Sort by `createdAt`."""
+  """By creation time, oldest first."""
   CREATED_AT
-  """Sort by `updatedAt`."""
+  """By last change, oldest first."""
   UPDATED_AT
 }
 ```