picked 0.0.101 → 0.0.102-next.2

package/docs/reference/management-api/schema/workspace-version.md

@@ -6,17 +6,16 @@ generated: true
 
 # Workspace version schema
 
-The operations and types that `workspace-version.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
 
 ### `workspaceDiff`
 
-Compute a structural diff between two workspace snapshots. Each side
-can be either a live workspace (diffed against its current draft
-snapshot) or a previously-published `WorkspaceVersion`. Requires
-authentication and `ORGANIZATION_PROJECTS_READ` scope on the project
-shared by both sides.
+Compares two workspace snapshots and lists the entities added, removed and modified. Each side is
+a workspace at its current content or a published version, and both sides must belong to one
+project.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 workspaceDiff(input: WorkspaceDiffInput!): WorkspaceDiffPayload! @auth
@@ -28,31 +27,26 @@ workspaceDiff(input: WorkspaceDiffInput!): WorkspaceDiffPayload! @auth
 
 ```graphql
 """
-An immutable snapshot of a workspace's config at publish time. Created
-by `workspacePublish`; never modified after creation.
-
-Snapshot contents (the underlying `config_json` blob) are deliberately
-not exposed via this type. To inspect the contents, use `workspaceDiff`
-to compare a snapshot against another snapshot or against the current
-draft.
+An immutable snapshot of a workspace, made when the workspace is published. Read its contents
+through `workspaceDiff`.
 """
 type WorkspaceVersion {
-  """Unique snapshot identifier."""
+  """The ID of the version."""
   id: ID!
-  """The workspace this snapshot belongs to."""
+  """The ID of the workspace the version was published from."""
   workspaceId: ID!
-  """The workspace this snapshot was published from."""
+  """The workspace the version was published from."""
   workspace: Workspace!
-  """Id of the hidden workspace duplicated at publish time, if one exists."""
+  """
+  The ID of the version's snapshot workspace. Null when the version has none.
+  """
   snapshotWorkspaceId: ID
   """
-  The hidden workspace duplicated from the published workspace at publish
-  time — the editable state behind this version, opened by Publish History's
-  Restore action. Null on versions published before snapshots existed, when
-  snapshot duplication failed, or after the snapshot workspace was deleted.
+  The hidden copy of the workspace made when the version was published, which restoring the
+  version opens. Null when the version has none or the copy was deleted.
   """
   snapshotWorkspace: Workspace
-  """When this snapshot was published."""
+  """When the version was published."""
   publishedAt: DateTime!
 }
 ```
@@ -60,11 +54,11 @@ type WorkspaceVersion {
 ### `WorkspaceVersionEdge`
 
 ```graphql
-"""Edge type for `WorkspaceVersionConnection`."""
+"""A workspace version in a page of results."""
 type WorkspaceVersionEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
-  """The workspace version."""
+  """The item."""
   node: WorkspaceVersion!
 }
 ```
@@ -72,15 +66,13 @@ type WorkspaceVersionEdge {
 ### `WorkspaceVersionConnection`
 
 ```graphql
-"""
-Relay-style connection of workspace versions, ordered newest-first by `publishedAt`.
-"""
+"""A page of workspace versions."""
 type WorkspaceVersionConnection {
-  """List of workspace-version edges."""
+  """The edges in this page."""
   edges: [WorkspaceVersionEdge!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of published versions for the workspace."""
+  """The number of items across all pages."""
   totalCount: Int!
 }
 ```
@@ -89,24 +81,17 @@ type WorkspaceVersionConnection {
 
 ```graphql
 """
-Input for `workspaceDiff`. Each side resolves to a snapshot: either a
-live workspace (diffed against its current draft snapshot) or a
-previously-published `WorkspaceVersion`.
-
-Exactly one of `baseWorkspaceId` / `baseWorkspaceVersionId` must be set,
-and exactly one of `compareWorkspaceId` / `compareWorkspaceVersionId`
-must be set. Both sides must resolve to the same project.
+The input of `workspaceDiff`. Each side is a workspace, at its current content, or a published
+version. Set exactly one field per side.
 """
 input WorkspaceDiffInput {
-  """Base-side live workspace (diffed against its current draft snapshot)."""
+  """The workspace to compare from."""
   baseWorkspaceId: ID
-  """Base-side published workspace version."""
+  """The version to compare from."""
   baseWorkspaceVersionId: ID
-  """
-  Compare-side live workspace (diffed against its current draft snapshot).
-  """
+  """The workspace to compare to."""
   compareWorkspaceId: ID
-  """Compare-side published workspace version."""
+  """The version to compare to."""
   compareWorkspaceVersionId: ID
 }
 ```
@@ -114,12 +99,14 @@ input WorkspaceDiffInput {
 ### `WorkspaceDiffPayload`
 
 ```graphql
-"""Payload returned by `workspaceDiff`."""
+"""The result of `workspaceDiff`."""
 type WorkspaceDiffPayload {
-  """The computed diff, or null when a `userError` was returned."""
+  """The diff. Null when a `userError` was returned."""
   diff: WorkspaceDiff
   """
-  Validation, authorisation, and referential-integrity errors. Empty array indicates success.
+  The problems that stopped the diff, with codes `INVALID_INPUT`, `WORKSPACE_NOT_FOUND`,
+  `WORKSPACE_VERSION_NOT_FOUND`, `PROJECT_NOT_FOUND`, `CROSS_PROJECT_COMPARISON_UNSUPPORTED` and
+  `FORBIDDEN`. Empty on success.
   """
   userErrors: [UserError!]!
 }
@@ -128,20 +115,16 @@ type WorkspaceDiffPayload {
 ### `WorkspaceSnapshotSummary`
 
 ```graphql
-"""
-Identifies a snapshot on one side of a diff — workspace id plus optional version id and publish time.
-"""
+"""One side of a diff."""
 type WorkspaceSnapshotSummary {
-  """
-  The workspace the snapshot belongs to (for both live workspaces and published versions).
-  """
+  """The ID of the workspace the side belongs to."""
   workspaceId: ID!
   """
-  The workspace-version id, when this side resolves to a published version.
+  The ID of the version. Null when the side is a workspace's current content.
   """
   workspaceVersionId: ID
   """
-  When the snapshot was published, when this side resolves to a published version.
+  When the version was published. Null when the side is a workspace's current content.
   """
   publishedAt: DateTime
 }
@@ -151,40 +134,35 @@ type WorkspaceSnapshotSummary {
 
 ```graphql
 """
-A workspace-level structural diff between two snapshots. Each top-level
-section enumerates entities that were added, removed, or modified for
-one entity kind.
-
-`hasChanges` is `true` iff any per-entity section is non-empty —
-convenient for showing a "no changes to publish" CTA without scanning
-every section.
+What differs between two workspace snapshots, one section per kind of entity. Each section lists
+the entities added, removed and modified.
 """
 type WorkspaceDiff {
-  """Identifier information for the base snapshot."""
+  """The side compared from."""
   base: WorkspaceSnapshotSummary!
-  """Identifier information for the compare snapshot."""
+  """The side compared to."""
   compare: WorkspaceSnapshotSummary!
-  """True iff any per-entity section is non-empty."""
+  """Whether any section lists an entity."""
   hasChanges: Boolean!
-  """Per-entity feature differences."""
+  """The feature flags that differ."""
   features: FeatureDiff!
-  """Per-entity step differences."""
+  """The steps that differ."""
   steps: StepDiff!
-  """Per-entity field differences."""
+  """The fields that differ."""
   fields: FieldDiff!
-  """Per-entity action differences."""
+  """The actions that differ."""
   actions: ActionDiff!
-  """Per-entity condition differences."""
+  """The conditions that differ."""
   conditions: ConditionDiff!
-  """Per-entity experience differences."""
+  """The experiences that differ."""
   experiences: ExperienceDiff!
-  """Per-entity CMS Content Model differences."""
+  """The Content Models that differ."""
   contentModels: ContentModelDiff!
-  """Per-entity CMS Content Block differences."""
+  """The Content Blocks that differ."""
   contentBlocks: ContentBlockDiff!
-  """Per-entity CMS Content Entry differences."""
+  """The content entries that differ."""
   contentEntries: ContentEntryDiff!
-  """Per-entity workflow differences."""
+  """The workflows that differ."""
   workflows: WorkflowDiff!
 }
 ```
@@ -192,13 +170,13 @@ type WorkspaceDiff {
 ### `PropertyChange`
 
 ```graphql
-"""A scalar or JSON-valued property that changed between two snapshots."""
+"""A property whose value differs between the two snapshots."""
 type PropertyChange {
-  """The property name on the parent entity (e.g. `name`, `weight`)."""
+  """The property's name, such as `name` or `weight`."""
   property: String!
-  """The base snapshot's value, as JSON."""
+  """The value in the base snapshot."""
   base: JSON
-  """The compare snapshot's value, as JSON."""
+  """The value in the compare snapshot."""
   compare: JSON
 }
 ```
@@ -207,17 +185,15 @@ type PropertyChange {
 
 ```graphql
 """
-A structural change to a JSON subtree (conditions' `logic`, fields'
-`validation`, Content Model schemas). Presented as two opaque JSON
-values rather than a fine-grained path diff — clients render their own
-visualisations.
+A JSON subtree that differs between the two snapshots, such as a condition's `logic` or a field's
+`validation`, given whole from each side.
 """
 type LogicChange {
-  """Which subtree changed (e.g. `logic`, `validation`)."""
+  """The subtree's name, such as `logic` or `validation`."""
   property: String!
-  """Base snapshot's subtree."""
+  """The subtree in the base snapshot."""
   base: JSON
-  """Compare snapshot's subtree."""
+  """The subtree in the compare snapshot."""
   compare: JSON
 }
 ```
@@ -225,16 +201,11 @@ type LogicChange {
 ### `FieldOptionSummary`
 
 ```graphql
-"""
-A selectable option within a field, summarised for diff display. Named
-`FieldOptionSummary` (not `FieldOption`) because the workspace's
-`FieldOption` type carries a `JSON` `value`, whereas diffing keys by a
-string `value` identity.
-"""
+"""A field option, as a diff lists it."""
 type FieldOptionSummary {
-  """Option machine value (identity key for diff comparison)."""
+  """The option's value, which identifies it across snapshots."""
   value: String!
-  """Option display label."""
+  """The option's label."""
   label: String!
 }
 ```
@@ -242,15 +213,13 @@ type FieldOptionSummary {
 ### `FieldOptionModification`
 
 ```graphql
-"""
-An option whose label changed while the `value` identity stayed the same.
-"""
+"""A field option whose label differs between the two snapshots."""
 type FieldOptionModification {
-  """The option's unchanged identity key."""
+  """The option's value."""
   value: String!
-  """Base snapshot's label."""
+  """The label in the base snapshot."""
   baseLabel: String!
-  """Compare snapshot's label."""
+  """The label in the compare snapshot."""
   compareLabel: String!
 }
 ```
@@ -258,13 +227,13 @@ type FieldOptionModification {
 ### `FieldOptionsChange`
 
 ```graphql
-"""Changes to a field's selectable options, keyed by option `value`."""
+"""How a field's options differ, matched by `value`."""
 type FieldOptionsChange {
   """Options present only in the compare snapshot."""
   added: [FieldOptionSummary!]!
   """Options present only in the base snapshot."""
   removed: [FieldOptionSummary!]!
-  """Options whose `label` changed (same `value`)."""
+  """Options whose label differs."""
   modified: [FieldOptionModification!]!
 }
 ```
@@ -272,13 +241,13 @@ type FieldOptionsChange {
 ### `DiffStepRef`
 
 ```graphql
-"""A reference to a step, used inside the diff payload."""
+"""A step, as a diff refers to it."""
 type DiffStepRef {
-  """Stable id of the referenced step."""
+  """The ID of the step."""
   id: ID!
-  """Display name from the snapshot."""
+  """Its name in the snapshot."""
   name: String!
-  """Stable, human-readable key from the snapshot."""
+  """Its key in the snapshot."""
   key: String!
 }
 ```
@@ -286,13 +255,13 @@ type DiffStepRef {
 ### `DiffFieldRef`
 
 ```graphql
-"""A reference to a field, used inside the diff payload."""
+"""A field, as a diff refers to it."""
 type DiffFieldRef {
-  """Stable id of the referenced field."""
+  """The ID of the field."""
   id: ID!
-  """Display name from the snapshot."""
+  """Its name in the snapshot."""
   name: String!
-  """Stable, human-readable key from the snapshot."""
+  """Its key in the snapshot."""
   key: String!
 }
 ```
@@ -300,13 +269,13 @@ type DiffFieldRef {
 ### `DiffActionRef`
 
 ```graphql
-"""A reference to an action, used inside the diff payload."""
+"""An action, as a diff refers to it."""
 type DiffActionRef {
-  """Stable id of the referenced action."""
+  """The ID of the action."""
   id: ID!
-  """Display name from the snapshot."""
+  """Its name in the snapshot."""
   name: String!
-  """Stable, human-readable key from the snapshot."""
+  """Its key in the snapshot."""
   key: String!
 }
 ```
@@ -314,13 +283,13 @@ type DiffActionRef {
 ### `DiffConditionRef`
 
 ```graphql
-"""A reference to a condition, used inside the diff payload."""
+"""A condition, as a diff refers to it."""
 type DiffConditionRef {
-  """Stable id of the referenced condition."""
+  """The ID of the condition."""
   id: ID!
-  """Display name from the snapshot."""
+  """Its name in the snapshot."""
   name: String!
-  """Stable, human-readable key from the snapshot."""
+  """Its key in the snapshot."""
   key: String!
 }
 ```
@@ -328,11 +297,11 @@ type DiffConditionRef {
 ### `FlowStepRefsChange`
 
 ```graphql
-"""Step refs added/removed from an experience's flow."""
+"""The steps added to or removed from an experience's flow."""
 type FlowStepRefsChange {
-  """Step refs referenced only in the compare snapshot."""
+  """Steps only the compare snapshot's flow uses."""
   added: [DiffStepRef!]!
-  """Step refs referenced only in the base snapshot."""
+  """Steps only the base snapshot's flow uses."""
   removed: [DiffStepRef!]!
 }
 ```
@@ -340,11 +309,11 @@ type FlowStepRefsChange {
 ### `FlowActionRefsChange`
 
 ```graphql
-"""Action refs added/removed from an experience's flow."""
+"""The actions added to or removed from an experience's flow."""
 type FlowActionRefsChange {
-  """Action refs referenced only in the compare snapshot."""
+  """Actions only the compare snapshot's flow uses."""
   added: [DiffActionRef!]!
-  """Action refs referenced only in the base snapshot."""
+  """Actions only the base snapshot's flow uses."""
   removed: [DiffActionRef!]!
 }
 ```
@@ -352,11 +321,11 @@ type FlowActionRefsChange {
 ### `FlowConditionRefsChange`
 
 ```graphql
-"""Condition refs added/removed from an experience's flow."""
+"""The conditions added to or removed from an experience's flow."""
 type FlowConditionRefsChange {
-  """Condition refs referenced only in the compare snapshot."""
+  """Conditions only the compare snapshot's flow uses."""
   added: [DiffConditionRef!]!
-  """Condition refs referenced only in the base snapshot."""
+  """Conditions only the base snapshot's flow uses."""
   removed: [DiffConditionRef!]!
 }
 ```
@@ -364,15 +333,13 @@ type FlowConditionRefsChange {
 ### `FieldRefsChange`
 
 ```graphql
-"""
-`Step.fieldIds` change — added/removed field refs, plus an order-only flag.
-"""
+"""How a step's fields differ."""
 type FieldRefsChange {
-  """Field refs present only in the compare snapshot."""
+  """Fields only the compare snapshot's step holds."""
   added: [DiffFieldRef!]!
-  """Field refs present only in the base snapshot."""
+  """Fields only the base snapshot's step holds."""
   removed: [DiffFieldRef!]!
-  """True iff the same set of refs is present in a different order."""
+  """Whether the step holds the same fields in a different order."""
   reordered: Boolean!
 }
 ```
@@ -380,21 +347,17 @@ type FieldRefsChange {
 ### `ExperienceFlowChange`
 
 ```graphql
-"""
-Summary of how an experience's flow graph changed. `structureChanged` is
-true when the graph (nodes/edges) differs beyond node/edge id renaming
-despite every referenced-entity set being equal — i.e. existing
-nodes/edges were re-arranged without changing what they reference.
-"""
+"""How an experience's flow differs."""
 type ExperienceFlowChange {
-  """Step ref changes, or null when unchanged."""
+  """The steps the flow added or removed. Null when they are the same."""
   stepRefsChange: FlowStepRefsChange
-  """Action ref changes, or null when unchanged."""
+  """The actions the flow added or removed. Null when they are the same."""
   actionRefsChange: FlowActionRefsChange
-  """Condition ref changes, or null when unchanged."""
+  """The conditions the flow added or removed. Null when they are the same."""
   conditionRefsChange: FlowConditionRefsChange
   """
-  True iff nodes/edges differ beyond id renaming while all referenced-entity sets are equal.
+  Whether the nodes or edges were rearranged while the flow uses the same steps, actions and
+  conditions. Node and edge IDs are ignored.
   """
   structureChanged: Boolean!
 }
@@ -403,13 +366,13 @@ type ExperienceFlowChange {
 ### `FeatureDiffEntry`
 
 ```graphql
-"""A feature's scalar property differences."""
+"""A feature flag whose properties differ."""
 type FeatureDiffEntry {
-  """Feature id (stable across snapshots)."""
+  """The ID of the feature flag."""
   id: ID!
-  """Display name of the feature, sourced from the compare snapshot."""
+  """Its name in the compare snapshot."""
   name: String!
-  """Scalar property changes."""
+  """The properties that differ."""
   propertyChanges: [PropertyChange!]!
 }
 ```
@@ -417,13 +380,13 @@ type FeatureDiffEntry {
 ### `FeatureDiff`
 
 ```graphql
-"""Feature section of the workspace diff."""
+"""The feature flags that differ between two snapshots."""
 type FeatureDiff {
-  """Features present only in the compare snapshot."""
+  """Feature flags present only in the compare snapshot."""
   added: [JSON!]!
-  """Features present only in the base snapshot."""
+  """Feature flags present only in the base snapshot."""
   removed: [JSON!]!
-  """Features present in both snapshots but with differing properties."""
+  """Feature flags present in both snapshots, with differing properties."""
   modified: [FeatureDiffEntry!]!
 }
 ```
@@ -431,17 +394,17 @@ type FeatureDiff {
 ### `StepDiffEntry`
 
 ```graphql
-"""A step's scalar property and field-ref differences."""
+"""A step whose properties or fields differ."""
 type StepDiffEntry {
-  """Step id (stable across snapshots)."""
+  """The ID of the step."""
   id: ID!
-  """Display name of the step, sourced from the compare snapshot."""
+  """Its name in the compare snapshot."""
   name: String!
-  """Stable, human-readable key, sourced from the compare snapshot."""
+  """Its key in the compare snapshot."""
   key: String!
-  """Scalar property changes."""
+  """The properties that differ."""
   propertyChanges: [PropertyChange!]!
-  """Field-ref change (the step's `fieldIds`), or null when unchanged."""
+  """How the step's fields differ. Null when they are the same."""
   fieldRefsChange: FieldRefsChange
 }
 ```
@@ -449,13 +412,13 @@ type StepDiffEntry {
 ### `StepDiff`
 
 ```graphql
-"""Step section of the workspace diff."""
+"""The steps that differ between two snapshots."""
 type StepDiff {
   """Steps present only in the compare snapshot."""
   added: [JSON!]!
   """Steps present only in the base snapshot."""
   removed: [JSON!]!
-  """Steps present in both snapshots but with differing properties."""
+  """Steps present in both snapshots, with differing properties."""
   modified: [StepDiffEntry!]!
 }
 ```
@@ -463,21 +426,21 @@ type StepDiff {
 ### `FieldDiffEntry`
 
 ```graphql
-"""A field's scalar, validation, and options differences."""
+"""A field whose properties, validation, condition or options differ."""
 type FieldDiffEntry {
-  """Field id (stable across snapshots)."""
+  """The ID of the field."""
   id: ID!
-  """Display name of the field, sourced from the compare snapshot."""
+  """Its name in the compare snapshot."""
   name: String!
-  """Stable, human-readable key, sourced from the compare snapshot."""
+  """Its key in the compare snapshot."""
   key: String!
-  """Scalar property changes."""
+  """The properties that differ."""
   propertyChanges: [PropertyChange!]!
-  """Validation subtree change, or null when unchanged."""
+  """How the validation differs. Null when it is the same."""
   validationChange: LogicChange
-  """Visibility-condition subtree change, or null when unchanged."""
+  """How the visibility condition differs. Null when it is the same."""
   conditionChange: LogicChange
-  """Options-set change, or null when unchanged."""
+  """How the options differ. Null when they are the same."""
   optionsChange: FieldOptionsChange
 }
 ```
@@ -485,13 +448,13 @@ type FieldDiffEntry {
 ### `FieldDiff`
 
 ```graphql
-"""Field section of the workspace diff."""
+"""The fields that differ between two snapshots."""
 type FieldDiff {
   """Fields present only in the compare snapshot."""
   added: [JSON!]!
   """Fields present only in the base snapshot."""
   removed: [JSON!]!
-  """Fields present in both snapshots but with differing properties."""
+  """Fields present in both snapshots, with differing properties."""
   modified: [FieldDiffEntry!]!
 }
 ```
@@ -499,15 +462,15 @@ type FieldDiff {
 ### `ActionDiffEntry`
 
 ```graphql
-"""An action's scalar property differences."""
+"""An action whose properties differ."""
 type ActionDiffEntry {
-  """Action id (stable across snapshots)."""
+  """The ID of the action."""
   id: ID!
-  """Display name of the action, sourced from the compare snapshot."""
+  """Its name in the compare snapshot."""
   name: String!
-  """Stable, human-readable key, sourced from the compare snapshot."""
+  """Its key in the compare snapshot."""
   key: String!
-  """Scalar property changes."""
+  """The properties that differ."""
   propertyChanges: [PropertyChange!]!
 }
 ```
@@ -515,13 +478,13 @@ type ActionDiffEntry {
 ### `ActionDiff`
 
 ```graphql
-"""Action section of the workspace diff."""
+"""The actions that differ between two snapshots."""
 type ActionDiff {
   """Actions present only in the compare snapshot."""
   added: [JSON!]!
   """Actions present only in the base snapshot."""
   removed: [JSON!]!
-  """Actions present in both snapshots but with differing properties."""
+  """Actions present in both snapshots, with differing properties."""
   modified: [ActionDiffEntry!]!
 }
 ```
@@ -529,17 +492,17 @@ type ActionDiff {
 ### `ConditionDiffEntry`
 
 ```graphql
-"""A condition's scalar and logic differences."""
+"""A condition whose properties or logic differ."""
 type ConditionDiffEntry {
-  """Condition id (stable across snapshots)."""
+  """The ID of the condition."""
   id: ID!
-  """Display name of the condition, sourced from the compare snapshot."""
+  """Its name in the compare snapshot."""
   name: String!
-  """Stable, human-readable key, sourced from the compare snapshot."""
+  """Its key in the compare snapshot."""
   key: String!
-  """Scalar property changes."""
+  """The properties that differ."""
   propertyChanges: [PropertyChange!]!
-  """Logic subtree change, or null when unchanged."""
+  """How the logic differs. Null when it is the same."""
   logicChange: LogicChange
 }
 ```
@@ -547,13 +510,13 @@ type ConditionDiffEntry {
 ### `ConditionDiff`
 
 ```graphql
-"""Condition section of the workspace diff."""
+"""The conditions that differ between two snapshots."""
 type ConditionDiff {
   """Conditions present only in the compare snapshot."""
   added: [JSON!]!
   """Conditions present only in the base snapshot."""
   removed: [JSON!]!
-  """Conditions present in both snapshots but with differing properties."""
+  """Conditions present in both snapshots, with differing properties."""
   modified: [ConditionDiffEntry!]!
 }
 ```
@@ -561,19 +524,19 @@ type ConditionDiff {
 ### `ExperienceDiffEntry`
 
 ```graphql
-"""An experience's scalar property, target, and flow differences."""
+"""An experience whose properties, targeting or flow differ."""
 type ExperienceDiffEntry {
-  """Experience id (stable across snapshots)."""
+  """The ID of the experience."""
   id: ID!
-  """Display name of the experience, sourced from the compare snapshot."""
+  """Its name in the compare snapshot."""
   name: String!
-  """Stable, human-readable key, sourced from the compare snapshot."""
+  """Its key in the compare snapshot."""
   key: String!
-  """Scalar property changes."""
+  """The properties that differ."""
   propertyChanges: [PropertyChange!]!
-  """Targeting change, or null when unchanged."""
+  """How the targeting differs. Null when it is the same."""
   targetChange: LogicChange
-  """Flow change, or null when unchanged."""
+  """How the flow differs. Null when it is the same."""
   flowChange: ExperienceFlowChange
 }
 ```
@@ -581,13 +544,13 @@ type ExperienceDiffEntry {
 ### `ExperienceDiff`
 
 ```graphql
-"""Experience section of the workspace diff."""
+"""The experiences that differ between two snapshots."""
 type ExperienceDiff {
   """Experiences present only in the compare snapshot."""
   added: [JSON!]!
   """Experiences present only in the base snapshot."""
   removed: [JSON!]!
-  """Experiences present in both snapshots but with differing properties."""
+  """Experiences present in both snapshots, with differing properties."""
   modified: [ExperienceDiffEntry!]!
 }
 ```
@@ -595,15 +558,15 @@ type ExperienceDiff {
 ### `ContentModelDiffEntry`
 
 ```graphql
-"""A Content Model's scalar and schema differences."""
+"""A Content Model whose properties or schema differ."""
 type ContentModelDiffEntry {
-  """Content Model id (stable across snapshots)."""
+  """The ID of the Content Model."""
   id: ID!
-  """Display name, sourced from the compare snapshot."""
+  """Its name in the compare snapshot."""
   name: String!
-  """Scalar property changes."""
+  """The properties that differ."""
   propertyChanges: [PropertyChange!]!
-  """Schema subtree change, or null when unchanged."""
+  """How the schema differs. Null when it is the same."""
   schemaChange: LogicChange
 }
 ```
@@ -611,15 +574,13 @@ type ContentModelDiffEntry {
 ### `ContentModelDiff`
 
 ```graphql
-"""Content Model section of the workspace diff."""
+"""The Content Models that differ between two snapshots."""
 type ContentModelDiff {
   """Content Models present only in the compare snapshot."""
   added: [JSON!]!
   """Content Models present only in the base snapshot."""
   removed: [JSON!]!
-  """
-  Content Models present in both snapshots but with differing properties.
-  """
+  """Content Models present in both snapshots, with differing properties."""
   modified: [ContentModelDiffEntry!]!
 }
 ```
@@ -627,15 +588,15 @@ type ContentModelDiff {
 ### `ContentBlockDiffEntry`
 
 ```graphql
-"""A Content Block's scalar and schema differences."""
+"""A Content Block whose properties or schema differ."""
 type ContentBlockDiffEntry {
-  """Content Block id (stable across snapshots)."""
+  """The ID of the Content Block."""
   id: ID!
-  """Display name, sourced from the compare snapshot."""
+  """Its name in the compare snapshot."""
   name: String!
-  """Scalar property changes."""
+  """The properties that differ."""
   propertyChanges: [PropertyChange!]!
-  """Schema subtree change, or null when unchanged."""
+  """How the schema differs. Null when it is the same."""
   schemaChange: LogicChange
 }
 ```
@@ -643,15 +604,13 @@ type ContentBlockDiffEntry {
 ### `ContentBlockDiff`
 
 ```graphql
-"""Content Block section of the workspace diff."""
+"""The Content Blocks that differ between two snapshots."""
 type ContentBlockDiff {
   """Content Blocks present only in the compare snapshot."""
   added: [JSON!]!
   """Content Blocks present only in the base snapshot."""
   removed: [JSON!]!
-  """
-  Content Blocks present in both snapshots but with differing properties.
-  """
+  """Content Blocks present in both snapshots, with differing properties."""
   modified: [ContentBlockDiffEntry!]!
 }
 ```
@@ -659,15 +618,15 @@ type ContentBlockDiff {
 ### `ContentEntryDiffEntry`
 
 ```graphql
-"""A Content Entry's scalar and data differences."""
+"""A content entry whose properties or data differ."""
 type ContentEntryDiffEntry {
-  """Content Entry id (stable across snapshots)."""
+  """The ID of the content entry."""
   id: ID!
-  """Parent Content Model id, sourced from the compare snapshot."""
+  """The ID of its Content Model in the compare snapshot."""
   contentModelId: ID!
-  """Scalar property changes."""
+  """The properties that differ."""
   propertyChanges: [PropertyChange!]!
-  """Data subtree change, or null when unchanged."""
+  """How the data differs. Null when it is the same."""
   dataChange: LogicChange
 }
 ```
@@ -675,15 +634,13 @@ type ContentEntryDiffEntry {
 ### `ContentEntryDiff`
 
 ```graphql
-"""Content Entry section of the workspace diff."""
+"""The content entries that differ between two snapshots."""
 type ContentEntryDiff {
-  """Content Entries present only in the compare snapshot."""
+  """Content entries present only in the compare snapshot."""
   added: [JSON!]!
-  """Content Entries present only in the base snapshot."""
+  """Content entries present only in the base snapshot."""
   removed: [JSON!]!
-  """
-  Content Entries present in both snapshots but with differing properties.
-  """
+  """Content entries present in both snapshots, with differing properties."""
   modified: [ContentEntryDiffEntry!]!
 }
 ```
@@ -692,22 +649,21 @@ type ContentEntryDiff {
 
 ```graphql
 """
-A workflow's trigger as the diff reports it. The action an `ACTION` trigger
-names is resolved against the snapshot the workflow belongs to, so a removed
-workflow still shows the action it was bound to.
+A workflow's trigger, as a diff reports it. An `ACTION` trigger's action is read from the
+workflow's own snapshot, so a removed workflow still shows its action.
 """
 type WorkflowDiffTrigger {
-  """Which kind of trigger this is."""
+  """The kind of trigger."""
   type: WorkflowTriggerType!
   """The event that starts the run. Set for an `EVENT` trigger only."""
   eventName: WorkflowEventName
   """
-  ID of the action whose run starts the workflow. Set for an `ACTION` trigger only.
+  The ID of the action whose run starts the workflow. Set for an `ACTION` trigger only.
   """
   actionId: ID
   """
-  The action `actionId` names, resolved from the snapshot. Null for an
-  `EVENT` trigger, and for an `ACTION` trigger whose action neither snapshot holds.
+  The action `actionId` names. Null for an `EVENT` trigger, and for an `ACTION` trigger whose
+  action neither snapshot holds.
   """
   action: DiffActionRef
 }
@@ -716,12 +672,12 @@ type WorkflowDiffTrigger {
 ### `WorkflowDiffNodeRef`
 
 ```graphql
-"""A node in a workflow graph, summarised for the diff."""
+"""A node in a workflow graph, as a diff lists it."""
 type WorkflowDiffNodeRef {
-  """Graph-unique node id, stable across snapshots of the same workflow."""
+  """The ID of the node, unique in its graph."""
   id: ID!
   """
-  The node kind as stored: `ORIGIN`, `TOOL`, `CONDITION` or `SLEEP`; `UNKNOWN` when missing.
+  The node's kind: `ORIGIN`, `TOOL`, `CONDITION` or `SLEEP`, or `UNKNOWN` when it has none.
   """
   type: String!
   """
@@ -735,26 +691,26 @@ type WorkflowDiffNodeRef {
 
 ```graphql
 """
-How a workflow's graph changed between two snapshots. Nodes are matched by
-id; a node's canvas position is layout and never makes it a modified node.
+How a workflow's graph differs between two snapshots. Nodes are matched by ID; moving a node on the
+canvas never makes it a modified node.
 """
 type WorkflowGraphChange {
-  """Number of nodes in the base snapshot's graph."""
+  """The number of nodes in the base snapshot's graph."""
   baseNodeCount: Int!
-  """Number of nodes in the compare snapshot's graph."""
+  """The number of nodes in the compare snapshot's graph."""
   compareNodeCount: Int!
-  """Number of edges in the base snapshot's graph."""
+  """The number of edges in the base snapshot's graph."""
   baseEdgeCount: Int!
-  """Number of edges in the compare snapshot's graph."""
+  """The number of edges in the compare snapshot's graph."""
   compareEdgeCount: Int!
   """Nodes present only in the compare snapshot."""
   addedNodes: [WorkflowDiffNodeRef!]!
   """Nodes present only in the base snapshot."""
   removedNodes: [WorkflowDiffNodeRef!]!
-  """Nodes present in both snapshots whose configuration differs."""
+  """Nodes present in both snapshots, with differing configuration."""
   modifiedNodes: [WorkflowDiffNodeRef!]!
   """
-  True iff the graph differs with no node added, removed or reconfigured: edges were rewired, or nodes moved.
+  Whether the graph differs with no node added, removed or reconfigured: edges were rewired, or nodes moved.
   """
   structureChanged: Boolean!
 }
@@ -763,19 +719,17 @@ type WorkflowGraphChange {
 ### `WorkflowDiffSummary`
 
 ```graphql
-"""
-A workflow as the diff lists it when it is present in one snapshot only.
-"""
+"""A workflow present in one snapshot only."""
 type WorkflowDiffSummary {
-  """Workflow id (stable across snapshots)."""
+  """The ID of the workflow."""
   id: ID!
-  """Display name of the workflow."""
+  """The workflow's name."""
   name: String!
-  """The trigger, or null when the stored trigger cannot be read."""
+  """The trigger. Null when it cannot be read."""
   trigger: WorkflowDiffTrigger
-  """Number of nodes in the workflow's graph."""
+  """The number of nodes in the workflow's graph."""
   nodeCount: Int!
-  """Number of edges in the workflow's graph."""
+  """The number of edges in the workflow's graph."""
   edgeCount: Int!
 }
 ```
@@ -783,21 +737,19 @@ type WorkflowDiffSummary {
 ### `WorkflowDiffEntry`
 
 ```graphql
-"""A workflow's scalar, trigger and graph differences."""
+"""A workflow whose properties, trigger or graph differ."""
 type WorkflowDiffEntry {
-  """Workflow id (stable across snapshots)."""
+  """The ID of the workflow."""
   id: ID!
-  """Display name of the workflow, sourced from the compare snapshot."""
+  """Its name in the compare snapshot."""
   name: String!
-  """
-  The compare snapshot's trigger, or null when the stored trigger cannot be read.
-  """
+  """The trigger in the compare snapshot. Null when it cannot be read."""
   trigger: WorkflowDiffTrigger
-  """Scalar property changes."""
+  """The properties that differ."""
   propertyChanges: [PropertyChange!]!
-  """Trigger subtree change, or null when unchanged."""
+  """How the trigger differs. Null when it is the same."""
   triggerChange: LogicChange
-  """Graph change, or null when unchanged."""
+  """How the graph differs. Null when it is the same."""
   graphChange: WorkflowGraphChange
 }
 ```
@@ -806,9 +758,8 @@ type WorkflowDiffEntry {
 
 ```graphql
 """
-Workflow section of the workspace diff. Workflows are frozen onto a version
-by `workspacePublish`, so a live workspace's workflows are compared against
-the copies the version froze.
+The workflows that differ between two snapshots. A version's workflows are the copies frozen when
+it was published.
 """
 type WorkflowDiff {
   """Workflows present only in the compare snapshot."""
@@ -816,7 +767,7 @@ type WorkflowDiff {
   """Workflows present only in the base snapshot."""
   removed: [WorkflowDiffSummary!]!
   """
-  Workflows present in both snapshots but with differing properties, trigger or graph.
+  Workflows present in both snapshots, with differing properties, trigger or graph.
   """
   modified: [WorkflowDiffEntry!]!
 }