picked 0.0.101 → 0.0.102-next.2

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

@@ -6,13 +6,14 @@ generated: true
 
 # Experience schema
 
-The operations and types that `experience.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
 
 ### `experience`
 
-Get an experience by ID within a workspace.
+Reads an experience.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 experience(id: ID!, workspaceId: ID!): Experience @auth
@@ -20,18 +21,32 @@ experience(id: ID!, workspaceId: ID!): Experience @auth
 
 ### `experiences`
 
-List experiences within a workspace. Filter by name with `search` (case-insensitive
-substring) and order with `sortKey` (default `NAME`) plus `reverse`.
+Lists the experiences in a workspace. `search` matches a case-insensitive substring of the name;
+`sortKey` and `reverse` set the order.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
-experiences(workspaceId: ID!, type: ExperienceType, first: Int, after: String, last: Int, before: String, search: String, sortKey: ExperienceSortKeys = NAME, reverse: Boolean = false): ExperienceConnection! @auth
+experiences(
+  workspaceId: ID!
+  """Only experiences of this kind. Null lists every kind."""
+  type: ExperienceType
+  first: Int
+  after: String
+  last: Int
+  before: String
+  search: String
+  sortKey: ExperienceSortKeys = NAME
+  reverse: Boolean = false
+): ExperienceConnection! @auth
 ```
 
 ## Mutations
 
 ### `experienceCreate`
 
-Create a new experience. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Creates an experience in a workspace. A `PAGE` experience gets its single step and flow graph
+automatically.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 experienceCreate(input: ExperienceCreateInput!): ExperienceCreatePayload! @auth
@@ -39,7 +54,8 @@ experienceCreate(input: ExperienceCreateInput!): ExperienceCreatePayload! @auth
 
 ### `experienceUpdate`
 
-Update an experience. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Updates an experience's settings. `experienceFlowUpdate` changes its flow graph.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 experienceUpdate(input: ExperienceUpdateInput!): ExperienceUpdatePayload! @auth
@@ -47,7 +63,8 @@ experienceUpdate(input: ExperienceUpdateInput!): ExperienceUpdatePayload! @auth
 
 ### `experienceDelete`
 
-Delete an experience. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Deletes an experience. Its steps, conditions and actions stay in the workspace.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 experienceDelete(input: ExperienceDeleteInput!): ExperienceDeletePayload! @auth
@@ -55,7 +72,10 @@ experienceDelete(input: ExperienceDeleteInput!): ExperienceDeletePayload! @auth
 
 ### `experienceFlowUpdate`
 
-Atomically save all changes to an experience flow. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Updates an experience's settings and flow graph, with the steps, conditions, actions and fields
+it uses, in one call. Validation runs before any write, and a change that fails it fails the
+whole call.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 experienceFlowUpdate(input: ExperienceFlowUpdateInput!): ExperienceFlowUpdatePayload! @auth
@@ -66,15 +86,15 @@ experienceFlowUpdate(input: ExperienceFlowUpdateInput!): ExperienceFlowUpdatePay
 ### `ExperienceNodeType`
 
 ```graphql
-"""Discriminator for `ExperienceNode` implementations."""
+"""The kinds of node in a flow graph."""
 enum ExperienceNodeType {
-  """The starting point of every flow graph. Exactly one per experience."""
+  """The node where every flow starts. One per experience."""
   ORIGIN
-  """A node that renders a step (UI)."""
+  """A node that shows a step."""
   STEP
-  """A node that evaluates a condition for branching."""
+  """A node that branches on a condition."""
   CONDITION
-  """A node that triggers an action (side effect)."""
+  """A node that starts an action."""
   ACTION
   """A node that launches another experience."""
   EXPERIENCE
@@ -84,14 +104,11 @@ enum ExperienceNodeType {
 ### `ExperienceEdgeHandle`
 
 ```graphql
-"""
-Edge handle for `ConditionNode` outgoing edges. Picks which branch of a
-condition the flow follows when the condition resolves true / false.
-"""
+"""The branch of a condition node that an edge leaves from."""
 enum ExperienceEdgeHandle {
-  """The TRUE branch of a `ConditionNode`."""
+  """The branch the flow takes when the condition is true."""
   TRUE
-  """The FALSE branch of a `ConditionNode`."""
+  """The branch the flow takes when the condition is false."""
   FALSE
 }
 ```
@@ -99,13 +116,11 @@ enum ExperienceEdgeHandle {
 ### `Position`
 
 ```graphql
-"""
-Position of a node on the flow graph canvas. Used purely for layout in the dashboard editor.
-"""
+"""A point on the flow canvas. It affects layout on the canvas only."""
 type Position {
-  """X coordinate (canvas units, can be negative)."""
+  """The horizontal coordinate. Can be negative."""
   x: Float!
-  """Y coordinate (canvas units, can be negative)."""
+  """The vertical coordinate. Can be negative."""
   y: Float!
 }
 ```
@@ -113,11 +128,11 @@ type Position {
 ### `PositionInput`
 
 ```graphql
-"""Input form of `Position`."""
+"""A point on the flow canvas, as input."""
 input PositionInput {
-  """X coordinate."""
+  """The horizontal coordinate."""
   x: Float!
-  """Y coordinate."""
+  """The vertical coordinate."""
   y: Float!
 }
 ```
@@ -125,17 +140,17 @@ input PositionInput {
 ### `ExperienceTargetPlacement`
 
 ```graphql
-"""
-Where the experience content is placed relative to the target DOM element.
-
-`REPLACE` swaps the target node out. `APPEND` / `PREPEND` add children
-inside the target. `BEFORE` / `AFTER` insert siblings around the target.
-"""
+"""Where an experience renders relative to its target element."""
 enum ExperienceTargetPlacement {
+  """In place of the target."""
   REPLACE
+  """Inside the target, after its children."""
   APPEND
+  """Inside the target, before its children."""
   PREPEND
+  """Before the target, as a sibling."""
   BEFORE
+  """After the target, as a sibling."""
   AFTER
 }
 ```
@@ -144,12 +159,12 @@ enum ExperienceTargetPlacement {
 
 ```graphql
 """
-A DOM target element and how the experience content is placed relative to it.
+An element an experience renders against, and where it renders relative to it.
 """
 type ExperienceTarget {
-  """CSS selector identifying the target DOM element."""
+  """The CSS selector that finds the target element."""
   selector: String!
-  """How the experience content is placed relative to the target element."""
+  """Where the experience renders relative to the target element."""
   placement: ExperienceTargetPlacement!
 }
 ```
@@ -157,11 +172,11 @@ type ExperienceTarget {
 ### `ExperienceTargetInput`
 
 ```graphql
-"""Input form of `ExperienceTarget`."""
+"""An element an experience renders against, as input."""
 input ExperienceTargetInput {
-  """CSS selector for the target DOM element."""
+  """The CSS selector that finds the target element."""
   selector: String!
-  """How the experience content is placed relative to the target element."""
+  """Where the experience renders relative to the target element."""
   placement: ExperienceTargetPlacement!
 }
 ```
@@ -169,17 +184,15 @@ input ExperienceTargetInput {
 ### `ExperienceType`
 
 ```graphql
-"""
-Experience kind discriminator.
-
-`FLOW` is a multi-step user journey driven by a flow graph. `PAGE` is a
-CMS-backed dynamic landing page with a single auto-created step.
-Mutations branch on this discriminator at create time.
-"""
+"""The kinds of experience. Fixed when the experience is created."""
 enum ExperienceType {
-  """Multi-step user journey driven by a flow graph."""
+  """
+  An interactive experience of one or more steps, driven by a flow graph.
+  """
   FLOW
-  """CMS-backed dynamic landing page with a single auto-created step."""
+  """
+  A standalone experience that your server renders from a content entry, with a single step.
+  """
   PAGE
 }
 ```
@@ -188,20 +201,16 @@ enum ExperienceType {
 
 ```graphql
 """
-Delivery status for an experience.
-
-`ACTIVE` is delivered to every request. `DRAFT` is omitted from the published
-payload, along with the steps, fields and actions only it references, and
-delivered only to a request carrying a valid preview token for the owning
-workspace.
-
-Status is captured in the published snapshot, so a change takes effect once the
-workspace is published again.
+Whether visitors receive an experience. The status is part of the published snapshot, so a change
+takes effect when the workspace is next published.
 """
 enum ExperienceStatus {
   """Delivered to every request."""
   ACTIVE
-  """Delivered only behind a valid preview token."""
+  """
+  Delivered only to a request carrying a valid preview token for the workspace. Left out of the
+  published payload, with the steps, fields and actions only it uses.
+  """
   DRAFT
 }
 ```
@@ -210,61 +219,52 @@ enum ExperienceStatus {
 
 ```graphql
 """
-An experience defines a user journey within a workspace. The flow graph
-is stored opaquely in `flowJson` and exposed structurally via `nodes` and
-`edges`.
-
-`targets` selects which DOM elements the experience attaches to. `key`
-is a stable identifier SDK consumers use to opt in to specific
-experiences. `condition` is a JSON Logic expression gating whether the
-experience renders at all.
+Personalised content that Picked serves to a visitor: a flow or a page.
 """
 type Experience {
-  """Unique experience identifier."""
+  """The ID of the experience."""
   id: ID!
-  """Display name of the experience."""
+  """The name of the experience."""
   name: String!
-  """DOM elements this experience attaches to, with placement strategy."""
+  """The elements the experience renders against."""
   targets: [ExperienceTarget!]!
-  """Stable, human-readable key for SDK consumers."""
+  """The stable identifier of the experience, unique within its workspace."""
   key: String!
-  """
-  Discriminator: `FLOW` (multi-step journey) or `PAGE` (CMS-backed landing).
-  """
+  """The kind of experience."""
   type: ExperienceType!
+  """Whether visitors receive the experience."""
+  status: ExperienceStatus!
   """
-  Delivery status: `ACTIVE` to everyone, `DRAFT` only behind a valid preview token.
+  The flow graph as stored JSON. `nodes` and `edges` carry the same graph, typed.
   """
-  status: ExperienceStatus!
-  """Opaque flow graph blob. Use `nodes` + `edges` for structured access."""
   flowJson: JSON
-  """Optional JSON Logic condition gating whether the experience renders."""
+  """
+  A JSON Logic rule that decides whether the experience renders. Null when none is set.
+  """
   condition: JSON
   """
-  JSON value controlling whether the experience initialises in an open state.
+  A JSON Logic rule that decides whether the experience starts open. Null when none is set.
   """
   initializeOpen: JSON
   """
-  Name of the React/Svelte component the SDK should render for this experience.
+  The component name that points the experience at a component in your application. Empty when none is set.
   """
   componentName: String!
-  """The workspace this experience belongs to."""
+  """The workspace the experience belongs to."""
   workspace: Workspace!
-  """Nodes in the flow graph, typed by their `__typename`."""
+  """The nodes of the flow graph."""
   nodes: [ExperienceNode!]!
-  """Edges in the flow graph connecting nodes."""
+  """The edges of the flow graph."""
   edges: [ExperienceEdge!]!
-  """All steps referenced by `STEP` nodes in this experience's flow."""
+  """The steps the flow's step nodes show."""
   steps: [Step!]!
-  """
-  All conditions referenced by `CONDITION` nodes in this experience's flow.
-  """
+  """The conditions the flow's condition nodes branch on."""
   conditions: [Condition!]!
-  """All actions referenced by `ACTION` nodes in this experience's flow."""
+  """The actions the flow's action nodes start."""
   actions: [Action!]!
-  """When this experience was created."""
+  """When the experience was created."""
   createdAt: DateTime!
-  """When this experience was last updated."""
+  """When the experience last changed."""
   updatedAt: DateTime!
 }
 ```
@@ -272,19 +272,15 @@ type Experience {
 ### `ExperienceConnection`
 
 ```graphql
-"""
-Relay-style connection of experiences, with both an `edges` list and a flat `nodes` accessor.
-"""
+"""A page of experiences."""
 type ExperienceConnection {
-  """List of experience edges."""
+  """The edges in this page."""
   edges: [ExperienceConnectionEdge!]!
-  """
-  Flat list of experiences, equivalent to `edges[].node`. Convenience accessor.
-  """
+  """The experiences in this page."""
   nodes: [Experience!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of experiences."""
+  """The number of experiences across all pages, ignoring `search`."""
   totalCount: Int!
 }
 ```
@@ -292,9 +288,9 @@ type ExperienceConnection {
 ### `ExperienceConnectionEdge`
 
 ```graphql
-"""Edge type for `ExperienceConnection`."""
+"""An experience in a page of results."""
 type ExperienceConnectionEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The experience."""
   node: Experience!
@@ -304,15 +300,13 @@ type ExperienceConnectionEdge {
 ### `ExperienceNode`
 
 ```graphql
-"""
-A node in the experience flow graph. Use `__typename` to discriminate the implementation.
-"""
+"""A node in an experience's flow graph. `__typename` names the kind."""
 interface ExperienceNode {
-  """Stable node identifier within the graph."""
+  """The ID of the node, unique within the graph."""
   id: ID!
-  """Node kind discriminator (also encoded in `__typename`)."""
+  """The kind of node."""
   type: ExperienceNodeType!
-  """Canvas position for the dashboard editor."""
+  """The position of the node on the canvas."""
   position: Position!
 }
 ```
@@ -320,10 +314,13 @@ interface ExperienceNode {
 ### `OriginNode`
 
 ```graphql
-"""Starting point of an experience flow. Exactly one per experience."""
+"""The node where every flow starts. One per experience."""
 type OriginNode implements ExperienceNode {
+  """The ID of the node, unique within the graph."""
   id: ID!
+  """The kind of node."""
   type: ExperienceNodeType!
+  """The position of the node on the canvas."""
   position: Position!
 }
 ```
@@ -331,12 +328,15 @@ type OriginNode implements ExperienceNode {
 ### `StepNode`
 
 ```graphql
-"""A node that renders a step's UI."""
+"""A node that shows a step."""
 type StepNode implements ExperienceNode {
+  """The ID of the node, unique within the graph."""
   id: ID!
+  """The kind of node."""
   type: ExperienceNodeType!
+  """The position of the node on the canvas."""
   position: Position!
-  """The step rendered when the flow reaches this node."""
+  """The step the node shows."""
   step: Step!
 }
 ```
@@ -345,13 +345,16 @@ type StepNode implements ExperienceNode {
 
 ```graphql
 """
-A node that evaluates a condition for branching. Outgoing edges carry `sourceHandle: TRUE | FALSE`.
+A node that branches on a condition. Its outgoing edges carry `sourceHandle` `TRUE` or `FALSE`.
 """
 type ConditionNode implements ExperienceNode {
+  """The ID of the node, unique within the graph."""
   id: ID!
+  """The kind of node."""
   type: ExperienceNodeType!
+  """The position of the node on the canvas."""
   position: Position!
-  """The condition evaluated when the flow reaches this node."""
+  """The condition the node evaluates."""
   condition: Condition!
 }
 ```
@@ -359,12 +362,15 @@ type ConditionNode implements ExperienceNode {
 ### `ActionNode`
 
 ```graphql
-"""A node that triggers an action (side effect)."""
+"""A node that starts an action."""
 type ActionNode implements ExperienceNode {
+  """The ID of the node, unique within the graph."""
   id: ID!
+  """The kind of node."""
   type: ExperienceNodeType!
+  """The position of the node on the canvas."""
   position: Position!
-  """The action triggered when the flow reaches this node."""
+  """The action the node starts."""
   action: Action!
 }
 ```
@@ -372,12 +378,15 @@ type ActionNode implements ExperienceNode {
 ### `LaunchExperienceNode`
 
 ```graphql
-"""A node that launches another experience. Used to compose experiences."""
+"""A node that launches another experience."""
 type LaunchExperienceNode implements ExperienceNode {
+  """The ID of the node, unique within the graph."""
   id: ID!
+  """The kind of node."""
   type: ExperienceNodeType!
+  """The position of the node on the canvas."""
   position: Position!
-  """The experience launched when the flow reaches this node."""
+  """The experience the node launches."""
   targetExperience: Experience!
 }
 ```
@@ -385,20 +394,20 @@ type LaunchExperienceNode implements ExperienceNode {
 ### `ExperienceEdge`
 
 ```graphql
-"""An edge connecting two nodes in the experience flow graph."""
+"""A link between two nodes of a flow graph."""
 type ExperienceEdge {
-  """Stable edge identifier within the graph."""
+  """The ID of the edge, unique within the graph."""
   id: ID!
-  """Source node (resolved)."""
+  """The node the edge leaves."""
   sourceNode: ExperienceNode!
-  """Destination node (resolved)."""
+  """The node the edge enters."""
   destinationNode: ExperienceNode!
-  """Source node id (denormalised)."""
+  """The ID of the node the edge leaves."""
   sourceNodeId: ID!
-  """Destination node id (denormalised)."""
+  """The ID of the node the edge enters."""
   destinationNodeId: ID!
   """
-  Only meaningful when the source is a `ConditionNode` — picks the TRUE / FALSE branch.
+  The branch the edge leaves a condition node from. Null when the source is not a condition node.
   """
   sourceHandle: ExperienceEdgeHandle
 }
@@ -408,22 +417,22 @@ type ExperienceEdge {
 
 ```graphql
 """
-Input form of a node in the flow graph. Only the field matching the node's `type` should be populated.
+A node of a flow graph, as input. Set only the reference that matches `type`.
 """
 input ExperienceNodeInput {
-  """Stable node identifier."""
+  """The ID of the node, unique within the graph."""
   id: ID!
-  """Node kind discriminator."""
+  """The kind of node."""
   type: ExperienceNodeType!
-  """Canvas position."""
+  """The position of the node on the canvas."""
   position: PositionInput!
-  """For STEP nodes: referenced step id."""
+  """The ID of the step a `STEP` node shows."""
   stepId: ID
-  """For CONDITION nodes: referenced condition id."""
+  """The ID of the condition a `CONDITION` node evaluates."""
   conditionId: ID
-  """For ACTION nodes: referenced action id."""
+  """The ID of the action an `ACTION` node starts."""
   actionId: ID
-  """For EXPERIENCE nodes: referenced experience id to launch."""
+  """The ID of the experience an `EXPERIENCE` node launches."""
   targetExperienceId: ID
 }
 ```
@@ -431,15 +440,15 @@ input ExperienceNodeInput {
 ### `ExperienceEdgeInput`
 
 ```graphql
-"""Input form of an edge in the flow graph."""
+"""An edge of a flow graph, as input."""
 input ExperienceEdgeInput {
-  """Stable edge identifier."""
+  """The ID of the edge, unique within the graph."""
   id: ID!
-  """Source node id."""
+  """The ID of the node the edge leaves."""
   sourceNodeId: ID!
-  """Destination node id."""
+  """The ID of the node the edge enters."""
   destinationNodeId: ID!
-  """For edges from a `ConditionNode`: which branch (TRUE / FALSE)."""
+  """The branch the edge leaves a condition node from."""
   sourceHandle: ExperienceEdgeHandle
 }
 ```
@@ -447,33 +456,35 @@ input ExperienceEdgeInput {
 ### `ExperienceCreateInput`
 
 ```graphql
-"""Input for `experienceCreate`."""
+"""The input of `experienceCreate`."""
 input ExperienceCreateInput {
-  """Workspace ID to create the experience in."""
+  """The ID of the workspace to create the experience in."""
   workspaceId: ID!
-  """Display name for the experience."""
+  """The name of the experience."""
   name: String!
-  """Stable, human-readable key for SDK consumers."""
-  key: String!
   """
-  Discriminator. `PAGE` auto-creates the singleton Step; `FLOW` uses the caller-supplied nodes / edges.
+  The stable identifier of the experience, unique within the workspace. It cannot change later.
   """
+  key: String!
+  """The kind of experience. Defaults to `FLOW`."""
   type: ExperienceType
-  """Delivery status. Defaults to `ACTIVE`."""
+  """Whether visitors receive the experience. Defaults to `ACTIVE`."""
   status: ExperienceStatus
-  """Optional JSON Logic condition gating whether the experience renders."""
+  """A JSON Logic rule that decides whether the experience renders."""
   condition: JSON
-  """Whether the experience should initialise in an open state."""
+  """A JSON Logic rule that decides whether the experience starts open."""
   initializeOpen: JSON
-  """Name of the React/Svelte component the SDK should render."""
-  componentName: String
   """
-  Targeting configuration — which DOM elements the experience attaches to.
+  The component name that points the experience at a component in your application.
   """
+  componentName: String
+  """The elements the experience renders against."""
   targets: [ExperienceTargetInput!]
-  """Initial flow graph nodes."""
+  """
+  The nodes of the flow graph. An origin node is added when none is given. Rejected for a `PAGE`.
+  """
   nodes: [ExperienceNodeInput!]
-  """Initial flow graph edges."""
+  """The edges of the flow graph. Rejected for a `PAGE`."""
   edges: [ExperienceEdgeInput!]
 }
 ```
@@ -481,7 +492,7 @@ input ExperienceCreateInput {
 ### `ExperienceCreatePayload`
 
 ```graphql
-"""Payload returned by `experienceCreate`."""
+"""The result of `experienceCreate`."""
 type ExperienceCreatePayload {
   """The created experience."""
   experience: Experience
@@ -491,21 +502,23 @@ type ExperienceCreatePayload {
 ### `ExperienceUpdateInput`
 
 ```graphql
-"""Input for `experienceUpdate`. Omit a field to leave it unchanged."""
+"""The input of `experienceUpdate`. Omit a field to keep its value."""
 input ExperienceUpdateInput {
-  """Experience ID."""
+  """The ID of the experience."""
   id: ID!
-  """New display name."""
+  """The name of the experience."""
   name: String
-  """New delivery status."""
+  """Whether visitors receive the experience."""
   status: ExperienceStatus
-  """New JSON Logic condition gating whether the experience renders."""
+  """A JSON Logic rule that decides whether the experience renders."""
   condition: JSON
-  """Whether the experience should initialise in an open state."""
+  """A JSON Logic rule that decides whether the experience starts open."""
   initializeOpen: JSON
-  """New component name."""
+  """
+  The component name that points the experience at a component in your application.
+  """
   componentName: String
-  """New targeting configuration."""
+  """The elements the experience renders against."""
   targets: [ExperienceTargetInput!]
 }
 ```
@@ -513,7 +526,7 @@ input ExperienceUpdateInput {
 ### `ExperienceUpdatePayload`
 
 ```graphql
-"""Payload returned by `experienceUpdate`."""
+"""The result of `experienceUpdate`."""
 type ExperienceUpdatePayload {
   """The updated experience."""
   experience: Experience
@@ -523,9 +536,9 @@ type ExperienceUpdatePayload {
 ### `ExperienceDeleteInput`
 
 ```graphql
-"""Input for `experienceDelete`."""
+"""The input of `experienceDelete`."""
 input ExperienceDeleteInput {
-  """Experience ID."""
+  """The ID of the experience."""
   id: ID!
 }
 ```
@@ -533,9 +546,9 @@ input ExperienceDeleteInput {
 ### `ExperienceDeletePayload`
 
 ```graphql
-"""Payload returned by `experienceDelete`."""
+"""The result of `experienceDelete`."""
 type ExperienceDeletePayload {
-  """ID of the deleted experience."""
+  """The ID of the deleted experience."""
   deletedExperienceId: ID
 }
 ```
@@ -543,36 +556,27 @@ type ExperienceDeletePayload {
 ### `ExperienceFlowUpdateInput`
 
 ```graphql
-"""
-Atomically save all changes to an experience flow in a single
-operation. Handles creation, updates, and deletion of nodes, edges,
-steps, conditions, actions, and fields.
-
-Set `allowPartialSuccess: true` to persist valid changes even when some
-fail validation; the failures appear in `errors` while successful
-changes are committed. Default (`false`) treats the operation as
-all-or-nothing.
-"""
+"""The input of `experienceFlowUpdate`. Omit a field to keep its value."""
 input ExperienceFlowUpdateInput {
-  """New display name."""
+  """The name of the experience."""
   name: String
-  """New delivery status."""
+  """Whether visitors receive the experience."""
   status: ExperienceStatus
-  """New JSON Logic condition gating whether the experience renders."""
+  """A JSON Logic rule that decides whether the experience renders."""
   condition: JSON
-  """Whether the experience should initialise in an open state."""
+  """A JSON Logic rule that decides whether the experience starts open."""
   initializeOpen: JSON
-  """New component name."""
+  """
+  The component name that points the experience at a component in your application.
+  """
   componentName: String
-  """New targeting configuration."""
+  """The elements the experience renders against."""
   targets: [ExperienceTargetInput!]
-  """The experience to update."""
+  """The ID of the experience."""
   experienceId: ID!
-  """All changes to apply to the experience flow."""
+  """The changes to the flow and the items it uses."""
   changes: ExperienceFlowChangesInput!
-  """
-  When true, valid changes are persisted even if some fail validation. When false (default), the entire operation fails if any change fails.
-  """
+  """Has no effect."""
   allowPartialSuccess: Boolean = false
 }
 ```
@@ -580,19 +584,19 @@ input ExperienceFlowUpdateInput {
 ### `ExperienceFlowChangesInput`
 
 ```graphql
-"""Container for all change operations grouped by entity type."""
+"""The changes in an `experienceFlowUpdate`, by kind of item."""
 input ExperienceFlowChangesInput {
-  """Step changes (workspace-level resources)."""
+  """The step changes."""
   steps: StepChangesInput
-  """Condition changes (workspace-level resources)."""
+  """The condition changes."""
   conditions: ConditionChangesInput
-  """Action changes (workspace-level resources)."""
+  """The action changes."""
   actions: ActionChangesInput
-  """Field changes (workspace-level resources)."""
+  """The field changes."""
   fields: FieldChangesInput
-  """Node changes in the flow graph."""
+  """The node changes."""
   nodes: ExperienceNodeChangesInput
-  """Edge changes connecting nodes."""
+  """The edge changes."""
   edges: ExperienceEdgeChangesInput
 }
 ```
@@ -600,15 +604,15 @@ input ExperienceFlowChangesInput {
 ### `StepChangesInput`
 
 ```graphql
-"""Step-level changes within an `experienceFlowUpdate` batch."""
+"""The step changes in an `experienceFlowUpdate`."""
 input StepChangesInput {
-  """
-  Steps to create. Each entry carries a `clientId` for cross-referencing from `nodes`.
-  """
+  """The steps to create."""
   create: [StepCreateData!]
-  """Steps to update."""
+  """The steps to update."""
   update: [StepUpdateData!]
-  """Step ids to delete."""
+  """
+  The IDs of steps that no node may reference after the save. The steps stay in the workspace.
+  """
   delete: [ID!]
 }
 ```
@@ -616,24 +620,30 @@ input StepChangesInput {
 ### `StepCreateData`
 
 ```graphql
-"""Data for creating a new step in the parent workspace."""
+"""A step to create in an `experienceFlowUpdate`."""
 input StepCreateData {
-  """Client-generated ID for mapping and cross-referencing."""
+  """
+  A client-chosen ID that other changes in the same call use to refer to the step.
+  """
   clientId: ID!
-  """Display name for the step."""
+  """The name of the step."""
   name: String!
-  """Unique key identifier for the step."""
+  """
+  The stable identifier of the step, unique within the workspace. It cannot change later.
+  """
   key: String!
-  """Optional description."""
+  """A description of the step."""
   description: String
-  """Layout name."""
+  """
+  The layout name: the component that renders the step, such as `card` or `modal`.
+  """
   layoutName: String
-  """IDs of existing workspace-level fields to reference."""
+  """The IDs of existing fields to put on the step, in order."""
   fieldIds: [ID!]
-  """Step content configuration (free-form JSON)."""
+  """Has no effect."""
   content: JSON
   """
-  ID of an existing step. When set, the create acts as an idempotent upsert against the existing step.
+  The ID of an existing step to use instead. `clientId` then maps to it, and nothing is written.
   """
   stepId: ID
 }
@@ -642,19 +652,23 @@ input StepCreateData {
 ### `StepUpdateData`
 
 ```graphql
-"""Data for updating an existing step."""
+"""
+A step to update in an `experienceFlowUpdate`. Omit a field to keep its value.
+"""
 input StepUpdateData {
-  """Step ID."""
+  """The ID of the step."""
   id: ID!
-  """New display name."""
+  """The name of the step."""
   name: String
-  """New description."""
+  """A description of the step."""
   description: String
-  """New layout name."""
+  """The layout name: the component that renders the step."""
   layoutName: String
-  """New field-id list (replaces the existing list when set)."""
+  """
+  The IDs of the fields on the step, in order. Replaces the current list.
+  """
   fieldIds: [ID!]
-  """New step content configuration."""
+  """Has no effect."""
   content: JSON
 }
 ```
@@ -662,15 +676,15 @@ input StepUpdateData {
 ### `ConditionChangesInput`
 
 ```graphql
-"""Condition-level changes within an `experienceFlowUpdate` batch."""
+"""The condition changes in an `experienceFlowUpdate`."""
 input ConditionChangesInput {
-  """
-  Conditions to create. Each entry carries a `clientId` for cross-referencing from `nodes`.
-  """
+  """The conditions to create."""
   create: [ConditionCreateData!]
-  """Conditions to update."""
+  """The conditions to update."""
   update: [ConditionUpdateData!]
-  """Condition ids to delete."""
+  """
+  The IDs of conditions that no node may reference after the save. The conditions stay in the workspace.
+  """
   delete: [ID!]
 }
 ```
@@ -678,18 +692,22 @@ input ConditionChangesInput {
 ### `ConditionCreateData`
 
 ```graphql
-"""Data for creating a new condition."""
+"""A condition to create in an `experienceFlowUpdate`."""
 input ConditionCreateData {
-  """Client-generated ID for mapping and cross-referencing."""
+  """
+  A client-chosen ID that other changes in the same call use to refer to the condition.
+  """
   clientId: 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 for condition evaluation."""
+  """The rule, as a JSON Logic expression."""
   logic: JSON!
   """
-  ID of an existing condition. When set, the create acts as an idempotent upsert against the existing condition.
+  The ID of an existing condition to use instead. `clientId` then maps to it, and nothing is written.
   """
   conditionId: ID
 }
@@ -698,13 +716,15 @@ input ConditionCreateData {
 ### `ConditionUpdateData`
 
 ```graphql
-"""Data for updating an existing condition."""
+"""
+A condition to update in an `experienceFlowUpdate`. Omit a field to keep its value.
+"""
 input ConditionUpdateData {
-  """Condition ID."""
+  """The ID of the condition."""
   id: ID!
-  """New display name."""
+  """The name of the condition."""
   name: String
-  """New JSON Logic expression."""
+  """The rule, as a JSON Logic expression."""
   logic: JSON
 }
 ```
@@ -712,15 +732,15 @@ input ConditionUpdateData {
 ### `ActionChangesInput`
 
 ```graphql
-"""Action-level changes within an `experienceFlowUpdate` batch."""
+"""The action changes in an `experienceFlowUpdate`."""
 input ActionChangesInput {
-  """
-  Actions to create. Each entry carries a `clientId` for cross-referencing from `nodes`.
-  """
+  """The actions to create."""
   create: [ActionCreateData!]
-  """Actions to update."""
+  """The actions to update."""
   update: [ActionUpdateData!]
-  """Action ids to delete."""
+  """
+  The IDs of actions that no node may reference after the save. The actions stay in the workspace.
+  """
   delete: [ID!]
 }
 ```
@@ -728,18 +748,22 @@ input ActionChangesInput {
 ### `ActionCreateData`
 
 ```graphql
-"""Data for creating a new action in the parent workspace."""
+"""An action to create in an `experienceFlowUpdate`."""
 input ActionCreateData {
-  """Client-generated ID for mapping and cross-referencing."""
+  """
+  A client-chosen ID that other changes in the same call use to refer to the action.
+  """
   clientId: ID!
-  """Display name for the action."""
+  """The name of the action."""
   name: String!
-  """Unique key identifier for the action."""
+  """
+  The stable identifier of the action, unique within the workspace. It cannot change later.
+  """
   key: String!
-  """Description of what this action does."""
+  """A description of the action."""
   description: String
   """
-  ID of an existing action. When set, the create acts as an idempotent upsert against the existing action.
+  The ID of an existing action to use instead. `clientId` then maps to it, and nothing is written.
   """
   actionId: ID
 }
@@ -748,17 +772,18 @@ input ActionCreateData {
 ### `ActionUpdateData`
 
 ```graphql
-"""Data for updating an existing action."""
+"""
+An action to update in an `experienceFlowUpdate`. Omit a field to keep its value.
+"""
 input ActionUpdateData {
-  """Action ID."""
+  """The ID of the action."""
   id: ID!
-  """New display name."""
+  """The name of the action."""
   name: String
-  """New description."""
+  """A description of the action."""
   description: String
   """
-  Replacement set of ids for the fields whose responses this action receives.
-  Omit to leave the set unchanged; pass an empty list to request nothing.
+  The IDs of the fields whose answers the action receives. Replaces the current set; an empty list clears it.
   """
   fieldIds: [ID!]
 }
@@ -767,15 +792,13 @@ input ActionUpdateData {
 ### `FieldChangesInput`
 
 ```graphql
-"""Field-level changes within an `experienceFlowUpdate` batch."""
+"""The field changes in an `experienceFlowUpdate`."""
 input FieldChangesInput {
-  """
-  Fields to create. Each entry carries a `clientId` and a step reference.
-  """
+  """The fields to create."""
   create: [FieldCreateData!]
-  """Fields to update."""
+  """The fields to update."""
   update: [FieldUpdateData!]
-  """Field ids to delete."""
+  """Has no effect."""
   delete: [ID!]
 }
 ```
@@ -783,52 +806,52 @@ input FieldChangesInput {
 ### `FieldCreateData`
 
 ```graphql
-"""Data for creating a new field in the parent workspace."""
+"""A field to create in an `experienceFlowUpdate`."""
 input FieldCreateData {
-  """Client-generated ID for mapping and cross-referencing."""
+  """
+  A client-chosen ID that other changes in the same call use to refer to the field.
+  """
   clientId: ID!
   """
-  Reference an existing step by server ID. Mutually exclusive with `stepClientId`.
+  The ID of an existing step to put the field on. Excludes `stepClientId`.
   """
   stepId: ID
   """
-  Reference a step being created in this same mutation. Mutually exclusive with `stepId`.
+  The `clientId` of a step created in the same call to put the field on. Excludes `stepId`.
   """
   stepClientId: ID
-  """Stable machine-readable name."""
+  """The machine-readable name of the field."""
   name: String!
-  """Unique key identifier for the field."""
+  """
+  The stable identifier of the field, unique within the workspace. It cannot change later.
+  """
   key: String!
-  """Human-readable label."""
+  """The label shown next to the input."""
   label: String!
-  """The field type."""
+  """The kind of value the field captures."""
   type: FieldType!
-  """Whether multiple values are allowed."""
+  """Whether the field accepts more than one value."""
   multiple: Boolean
-  """Whether the field is required."""
+  """Whether the visitor must answer the field."""
   required: Boolean
-  """Validation rules as a JSON-encoded string. Parsed server-side."""
+  """The validation rules, as a JSON string."""
   validationString: String
-  """JSON default value."""
+  """The value the field starts with."""
   defaultValue: JSON
-  """JSON Logic condition controlling whether the field is rendered."""
+  """A JSON Logic rule that decides whether the field renders."""
   condition: JSON
-  """Placeholder text."""
+  """The text shown in the empty input."""
   placeholder: String
-  """Description."""
+  """A description shown with the label."""
   description: String
-  """Help text."""
+  """A hint shown below the field."""
   helpText: String
-  """
-  When true, the captured value is excluded from analytics tracking. Omitted defaults to `true`: tracking is opt-in.
-  """
+  """Whether the answer is left out of analytics. Defaults to `true`."""
   doNotTrack: Boolean
-  """
-  When true, the captured value is excluded from persistence. Omitted defaults to `true`: persistence is opt-in.
-  """
+  """Whether the answer is left out of storage. Defaults to `true`."""
   doNotStore: Boolean
   """
-  ID of an existing field. When set, the create acts as an idempotent upsert against the existing field.
+  The ID of an existing field to use instead. `clientId` then maps to it, and nothing is written.
   """
   fieldId: ID
 }
@@ -837,39 +860,41 @@ input FieldCreateData {
 ### `FieldUpdateData`
 
 ```graphql
-"""Data for updating an existing field."""
+"""
+A field to update in an `experienceFlowUpdate`. Omit a field to keep its value. `type` is required.
+"""
 input FieldUpdateData {
-  """Field ID."""
+  """The ID of the field."""
   id: ID!
-  """New machine-readable name."""
+  """The machine-readable name of the field."""
   name: String
-  """New label."""
+  """The label shown next to the input."""
   label: String
   """
-  Field type. Required even when unchanged — used to coerce other fields server-side.
+  The kind of value the field captures. Required: send the current type to keep it.
   """
   type: FieldType!
-  """Whether multiple values are allowed."""
+  """Whether the field accepts more than one value."""
   multiple: Boolean
-  """Whether the field is required."""
+  """Whether the visitor must answer the field."""
   required: Boolean
-  """Validation rules as a JSON-encoded string."""
+  """The validation rules, as a JSON string."""
   validationString: String
-  """JSON default value."""
+  """The value the field starts with."""
   defaultValue: JSON
-  """JSON Logic condition controlling whether the field is rendered."""
+  """A JSON Logic rule that decides whether the field renders."""
   condition: JSON
-  """Placeholder text."""
+  """The text shown in the empty input."""
   placeholder: String
-  """Description."""
+  """A description shown with the label."""
   description: String
-  """Help text."""
+  """A hint shown below the field."""
   helpText: String
-  """When true, the captured value is excluded from analytics tracking."""
+  """Whether the answer is left out of analytics."""
   doNotTrack: Boolean
-  """When true, the captured value is excluded from persistence."""
+  """Whether the answer is left out of storage."""
   doNotStore: Boolean
-  """Field options as a JSON array."""
+  """The choices, as a JSON array."""
   options: JSON
 }
 ```
@@ -877,13 +902,13 @@ input FieldUpdateData {
 ### `ExperienceNodeChangesInput`
 
 ```graphql
-"""Node-level changes within an `experienceFlowUpdate` batch."""
+"""The node changes in an `experienceFlowUpdate`."""
 input ExperienceNodeChangesInput {
-  """Nodes to create."""
+  """The nodes to create."""
   create: [ExperienceNodeCreateData!]
-  """Nodes to update."""
+  """The nodes to update."""
   update: [ExperienceNodeUpdateData!]
-  """Node ids to delete."""
+  """The IDs of the nodes to delete."""
   delete: [ID!]
 }
 ```
@@ -892,47 +917,44 @@ input ExperienceNodeChangesInput {
 
 ```graphql
 """
-Data for creating a new node in the flow graph. The fields populated
-depend on `type`:
-
-- `STEP`: `stepId` or `stepClientId` (mutually exclusive).
-- `CONDITION`: `conditionId` or `conditionClientId`.
-- `ACTION`: `actionId` or `actionClientId`.
-- `EXPERIENCE`: `targetExperienceId`.
-- `ORIGIN`: no extras.
+A node to create in an `experienceFlowUpdate`. Set only the reference that matches `type`: a step
+for `STEP`, a condition for `CONDITION`, an action for `ACTION`, an experience for `EXPERIENCE`,
+and none for `ORIGIN`.
 """
 input ExperienceNodeCreateData {
-  """Client-generated ID for mapping and cross-referencing from edges."""
+  """
+  A client-chosen ID that edges in the same call use to refer to the node.
+  """
   clientId: ID!
-  """Node kind discriminator."""
+  """The kind of node."""
   type: ExperienceNodeType!
-  """Canvas position."""
+  """The position of the node on the canvas."""
   position: PositionInput!
   """
-  For STEP nodes: reference an existing step by server ID. Mutually exclusive with `stepClientId`.
+  The ID of an existing step a `STEP` node shows. Excludes `stepClientId`.
   """
   stepId: ID
   """
-  For STEP nodes: reference a step being created in this same mutation. Mutually exclusive with `stepId`.
+  The `clientId` of a step created in the same call that a `STEP` node shows. Excludes `stepId`.
   """
   stepClientId: ID
   """
-  For CONDITION nodes: reference an existing condition by server ID. Mutually exclusive with `conditionClientId`.
+  The ID of an existing condition a `CONDITION` node evaluates. Excludes `conditionClientId`.
   """
   conditionId: ID
   """
-  For CONDITION nodes: reference a condition being created in this same mutation. Mutually exclusive with `conditionId`.
+  The `clientId` of a condition created in the same call that a `CONDITION` node evaluates. Excludes `conditionId`.
   """
   conditionClientId: ID
   """
-  For ACTION nodes: reference an existing workspace-level action. Mutually exclusive with `actionClientId`.
+  The ID of an existing action an `ACTION` node starts. Excludes `actionClientId`.
   """
   actionId: ID
   """
-  For ACTION nodes: reference an action being created in this same mutation. Mutually exclusive with `actionId`.
+  The `clientId` of an action created in the same call that an `ACTION` node starts. Excludes `actionId`.
   """
   actionClientId: ID
-  """For EXPERIENCE nodes: reference target experience to launch."""
+  """The ID of the experience an `EXPERIENCE` node launches."""
   targetExperienceId: ID
 }
 ```
@@ -940,19 +962,21 @@ input ExperienceNodeCreateData {
 ### `ExperienceNodeUpdateData`
 
 ```graphql
-"""Data for updating an existing node."""
+"""
+A node to update in an `experienceFlowUpdate`. Only its position changes.
+"""
 input ExperienceNodeUpdateData {
-  """Node ID."""
+  """The ID of the node."""
   id: ID!
-  """New canvas position."""
+  """The position of the node on the canvas."""
   position: PositionInput!
-  """For STEP nodes: new step reference."""
+  """Has no effect."""
   stepId: ID
-  """For CONDITION nodes: new condition reference."""
+  """Has no effect."""
   conditionId: ID
-  """For ACTION nodes: new action reference."""
+  """Has no effect."""
   actionId: ID
-  """For EXPERIENCE nodes: new target experience."""
+  """Has no effect."""
   targetExperienceId: ID
 }
 ```
@@ -960,13 +984,13 @@ input ExperienceNodeUpdateData {
 ### `ExperienceEdgeChangesInput`
 
 ```graphql
-"""Edge-level changes within an `experienceFlowUpdate` batch."""
+"""The edge changes in an `experienceFlowUpdate`."""
 input ExperienceEdgeChangesInput {
-  """Edges to create."""
+  """The edges to create."""
   create: [ExperienceEdgeCreateInput!]
-  """Edges to update."""
+  """The edges to update."""
   update: [ExperienceEdgeUpdateInput!]
-  """Edge ids to delete."""
+  """The IDs of the edges to delete."""
   delete: [ID!]
 }
 ```
@@ -974,27 +998,27 @@ input ExperienceEdgeChangesInput {
 ### `ExperienceEdgeCreateInput`
 
 ```graphql
-"""Data for creating a new edge."""
+"""An edge to create in an `experienceFlowUpdate`."""
 input ExperienceEdgeCreateInput {
-  """Client-generated ID for this edge."""
+  """A client-chosen ID for the edge."""
   clientId: ID!
   """
-  Source node by server ID. Mutually exclusive with `sourceNodeClientId`.
+  The ID of an existing node the edge leaves. Excludes `sourceNodeClientId`.
   """
   sourceNodeId: ID
   """
-  Source node being created in this same mutation. Mutually exclusive with `sourceNodeId`.
+  The `clientId` of a node created in the same call that the edge leaves. Excludes `sourceNodeId`.
   """
   sourceNodeClientId: ID
   """
-  Destination node by server ID. Mutually exclusive with `destinationNodeClientId`.
+  The ID of an existing node the edge enters. Excludes `destinationNodeClientId`.
   """
   destinationNodeId: ID
   """
-  Destination node being created in this same mutation. Mutually exclusive with `destinationNodeId`.
+  The `clientId` of a node created in the same call that the edge enters. Excludes `destinationNodeId`.
   """
   destinationNodeClientId: ID
-  """For edges from conditional nodes: which branch (TRUE / FALSE)."""
+  """The branch the edge leaves a condition node from."""
   sourceHandle: ExperienceEdgeHandle
 }
 ```
@@ -1002,15 +1026,17 @@ input ExperienceEdgeCreateInput {
 ### `ExperienceEdgeUpdateInput`
 
 ```graphql
-"""Data for updating an existing edge."""
+"""
+An edge to update in an `experienceFlowUpdate`. Omit a field to keep its value.
+"""
 input ExperienceEdgeUpdateInput {
-  """Edge ID."""
+  """The ID of the edge."""
   id: ID!
-  """New source node id."""
+  """The ID of the node the edge leaves."""
   sourceNodeId: ID
-  """New destination node id."""
+  """The ID of the node the edge enters."""
   destinationNodeId: ID
-  """New conditional branch handle."""
+  """The branch the edge leaves a condition node from."""
   sourceHandle: ExperienceEdgeHandle
 }
 ```
@@ -1018,15 +1044,15 @@ input ExperienceEdgeUpdateInput {
 ### `ExperienceFlowUpdatePayload`
 
 ```graphql
-"""Payload returned by `experienceFlowUpdate`."""
+"""The result of `experienceFlowUpdate`."""
 type ExperienceFlowUpdatePayload {
-  """The updated experience with all changes applied."""
+  """The experience with the changes applied."""
   experience: Experience
+  """The server ID for each `clientId` in the input."""
+  idMappings: ExperienceFlowIdMappings!
   """
-  Mappings from client-generated IDs to server-generated IDs, grouped by entity kind.
+  Always empty. A change that fails validation fails the whole operation with an error.
   """
-  idMappings: ExperienceFlowIdMappings!
-  """Validation errors. Empty array indicates success."""
   errors: [UserError!]!
 }
 ```
@@ -1035,20 +1061,20 @@ type ExperienceFlowUpdatePayload {
 
 ```graphql
 """
-Categorised client-to-server ID mappings emitted by `experienceFlowUpdate`.
+The server IDs that `experienceFlowUpdate` assigned to each `clientId`, by kind of item.
 """
 type ExperienceFlowIdMappings {
-  """Step id mappings."""
+  """The step IDs."""
   steps: [IdMapping!]!
-  """Condition id mappings."""
+  """The condition IDs."""
   conditions: [IdMapping!]!
-  """Action id mappings."""
+  """The action IDs."""
   actions: [IdMapping!]!
-  """Field id mappings."""
+  """The field IDs."""
   fields: [IdMapping!]!
-  """Node id mappings."""
+  """The node IDs."""
   nodes: [IdMapping!]!
-  """Edge id mappings."""
+  """The edge IDs."""
   edges: [IdMapping!]!
 }
 ```
@@ -1056,11 +1082,13 @@ type ExperienceFlowIdMappings {
 ### `IdMapping`
 
 ```graphql
-"""Maps a client-generated ID to a server-generated ID."""
+"""
+A client-chosen ID paired with the server ID of the item it stands for.
+"""
 type IdMapping {
-  """The ID provided by the client in the create operation."""
+  """The ID the client chose."""
   clientId: ID!
-  """The ID generated by the server for the created entity."""
+  """The server ID of the created or reused item."""
   id: ID!
 }
 ```
@@ -1069,14 +1097,12 @@ type IdMapping {
 
 ```graphql
 """
-An experience that references a workspace resource, preventing its
-deletion. Returned in `ActionDeleteUserError`, `ConditionDeleteUserError`,
-and `StepDeleteUserError` when the delete is blocked by usage.
+An experience that references a workspace item and so blocks its delete.
 """
 type ReferencingExperience {
-  """The experience id."""
+  """The ID of the experience."""
   id: ID!
-  """The experience name."""
+  """The name of the experience."""
   name: String!
 }
 ```
@@ -1084,15 +1110,13 @@ type ReferencingExperience {
 ### `ExperienceSortKeys`
 
 ```graphql
-"""
-Sort keys for `experiences(...)`. Pair with `reverse: true` to flip the order (`NAME` + `reverse: false` sorts A→Z; `CREATED_AT` + `reverse: true` is newest-first).
-"""
+"""The orders `experiences` can sort by. `reverse: true` flips each."""
 enum ExperienceSortKeys {
-  """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
 }
 ```