picked 0.0.101 → 0.0.102-next.2

package/docs/reference/management-api/schema/cms-models.md

@@ -6,21 +6,36 @@ generated: true
 
 # Cms models schema
 
-The operations and types that `cms-models.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
 
 ### `contentModels`
 
-List CMS Content Models in a workspace, optionally filtered by category.
+Lists the models in a workspace.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
-contentModels(workspaceId: ID!, category: ContentModelCategory, first: Int, after: String, last: Int, before: String, search: String, sortKey: ContentModelSortKeys = NAME, reverse: Boolean = false): ContentModelConnection! @auth
+contentModels(
+  workspaceId: ID!
+  """The role to filter by. Omit it for every model."""
+  category: ContentModelCategory
+  first: Int
+  after: String
+  last: Int
+  before: String
+  """Text that the model name contains, ignoring case."""
+  search: String
+  sortKey: ContentModelSortKeys = NAME
+  """Whether to reverse the order of `sortKey`."""
+  reverse: Boolean = false
+): ContentModelConnection! @auth
 ```
 
 ### `contentModel`
 
-Fetch a CMS Content Model by id.
+Reads a model.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 contentModel(id: ID!): ContentModel @auth
@@ -28,15 +43,30 @@ contentModel(id: ID!): ContentModel @auth
 
 ### `contentBlocks`
 
-List CMS Content Blocks in a workspace, optionally filtered by category.
+Lists the blocks in a workspace.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
-contentBlocks(workspaceId: ID!, category: ContentBlockCategory, first: Int, after: String, last: Int, before: String, search: String, sortKey: ContentBlockSortKeys = NAME, reverse: Boolean = false): ContentBlockConnection! @auth
+contentBlocks(
+  workspaceId: ID!
+  """The role to filter by. Omit it for every block."""
+  category: ContentBlockCategory
+  first: Int
+  after: String
+  last: Int
+  before: String
+  """Text that the block name contains, ignoring case."""
+  search: String
+  sortKey: ContentBlockSortKeys = NAME
+  """Whether to reverse the order of `sortKey`."""
+  reverse: Boolean = false
+): ContentBlockConnection! @auth
 ```
 
 ### `contentBlock`
 
-Fetch a CMS Content Block by id.
+Reads a block.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 contentBlock(id: ID!): ContentBlock @auth
@@ -44,15 +74,28 @@ contentBlock(id: ID!): ContentBlock @auth
 
 ### `contentEntries`
 
-List CMS Content Entries in a workspace, optionally filtered by parent Content Model.
+Lists the content entries in a workspace.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
-contentEntries(workspaceId: ID!, contentModelId: ID, first: Int, after: String, last: Int, before: String, sortKey: ContentEntrySortKeys = CREATED_AT, reverse: Boolean = false): ContentEntryConnection! @auth
+contentEntries(
+  workspaceId: ID!
+  """The ID of the model to filter by. Omit it for every content entry."""
+  contentModelId: ID
+  first: Int
+  after: String
+  last: Int
+  before: String
+  sortKey: ContentEntrySortKeys = CREATED_AT
+  """Whether to reverse the order of `sortKey`."""
+  reverse: Boolean = false
+): ContentEntryConnection! @auth
 ```
 
 ### `contentEntry`
 
-Fetch a CMS Content Entry by id.
+Reads a content entry.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 contentEntry(id: ID!): ContentEntry @auth
@@ -60,15 +103,34 @@ contentEntry(id: ID!): ContentEntry @auth
 
 ### `assets`
 
-List CMS Assets in a project, with optional text search, MIME-type filtering, and sort.
+Lists the assets in a project, newest first by default.
+Scope: `ORGANIZATION_PROJECTS_READ`.
 
 ```graphql
-assets(projectId: ID!, first: Int, after: String, last: Int, before: String, search: String, kind: AssetKind, acceptedMimeTypes: [String!], sortKey: AssetSortKeys = CREATED_AT, reverse: Boolean = true): AssetConnection! @auth
+assets(
+  projectId: ID!
+  first: Int
+  after: String
+  last: Int
+  before: String
+  """Text that the file name contains, ignoring case."""
+  search: String
+  """The media type group to filter by."""
+  kind: AssetKind
+  """
+  The MIME types to filter by. An entry such as `image/*` matches every subtype.
+  """
+  acceptedMimeTypes: [String!]
+  sortKey: AssetSortKeys = CREATED_AT
+  """Whether to reverse the order of `sortKey`."""
+  reverse: Boolean = true
+): AssetConnection! @auth
 ```
 
 ### `asset`
 
-Fetch a CMS Asset by id.
+Reads an asset.
+Scope: `ORGANIZATION_PROJECTS_READ`.
 
 ```graphql
 asset(id: ID!): Asset @auth
@@ -76,21 +138,24 @@ asset(id: ID!): Asset @auth
 
 ### `workspaceContentEntryValidation`
 
-Run schema validation across every Content Entry in a workspace and
-report which rows no longer conform. Read-only — does not auto-fix.
-Useful as a pre-publish sanity gate, especially after a Content Block
-schema change. Optionally narrow the sweep to a single Content Model
-with `contentModelId`.
+Verifies each content entry in a workspace against its model's schema, including embedded blocks.
+It changes no data.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
-workspaceContentEntryValidation(workspaceId: ID!, contentModelId: ID): WorkspaceContentEntryValidationPayload! @auth
+workspaceContentEntryValidation(
+  workspaceId: ID!
+  """The ID of a model, to check only its content entries."""
+  contentModelId: ID
+): WorkspaceContentEntryValidationPayload! @auth
 ```
 
 ## Mutations
 
 ### `contentModelCreate`
 
-Create a new CMS Content Model. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Creates a model.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 contentModelCreate(input: ContentModelCreateInput!): ContentModelCreatePayload! @auth
@@ -98,7 +163,9 @@ contentModelCreate(input: ContentModelCreateInput!): ContentModelCreatePayload!
 
 ### `contentModelUpdate`
 
-Update a CMS Content Model. Returns migration warnings when the schema change drops or coerces dependent Content Entry fields.
+Updates a model. A schema change migrates the data of its content entries and lists each
+removed value in `migrationWarnings`.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 contentModelUpdate(input: ContentModelUpdateInput!): ContentModelUpdatePayload! @auth
@@ -106,7 +173,9 @@ contentModelUpdate(input: ContentModelUpdateInput!): ContentModelUpdatePayload!
 
 ### `contentModelDelete`
 
-Soft-delete a CMS Content Model. Refuses if dependent Content Entry rows still exist.
+Deletes a model. Fails with `CONFLICT` while content entries use it, or while another schema's
+reference field targets it.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 contentModelDelete(input: ContentModelDeleteInput!): ContentModelDeletePayload! @auth
@@ -114,7 +183,8 @@ contentModelDelete(input: ContentModelDeleteInput!): ContentModelDeletePayload!
 
 ### `contentBlockCreate`
 
-Create a new CMS Content Block. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Creates a block.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 contentBlockCreate(input: ContentBlockCreateInput!): ContentBlockCreatePayload! @auth
@@ -122,7 +192,8 @@ contentBlockCreate(input: ContentBlockCreateInput!): ContentBlockCreatePayload!
 
 ### `contentBlockUpdate`
 
-Update a CMS Content Block schema.
+Updates a block. A schema change does not migrate the content entries that embed it.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 contentBlockUpdate(input: ContentBlockUpdateInput!): ContentBlockUpdatePayload! @auth
@@ -130,7 +201,8 @@ contentBlockUpdate(input: ContentBlockUpdateInput!): ContentBlockUpdatePayload!
 
 ### `contentBlockDelete`
 
-Soft-delete a CMS Content Block.
+Deletes a block.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 contentBlockDelete(input: ContentBlockDeleteInput!): ContentBlockDeletePayload! @auth
@@ -138,7 +210,9 @@ contentBlockDelete(input: ContentBlockDeleteInput!): ContentBlockDeletePayload!
 
 ### `contentEntryCreate`
 
-Create a new CMS Content Entry against a parent Content Model.
+Creates a content entry of a model. Each asset reference without a version is pinned to the
+asset's current version.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 contentEntryCreate(input: ContentEntryCreateInput!): ContentEntryCreatePayload! @auth
@@ -146,7 +220,9 @@ contentEntryCreate(input: ContentEntryCreateInput!): ContentEntryCreatePayload!
 
 ### `contentEntryUpdate`
 
-Update a CMS Content Entry's data.
+Updates the data of a content entry. Each asset reference without a version is pinned to the
+asset's current version.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 contentEntryUpdate(input: ContentEntryUpdateInput!): ContentEntryUpdatePayload! @auth
@@ -154,7 +230,9 @@ contentEntryUpdate(input: ContentEntryUpdateInput!): ContentEntryUpdatePayload!
 
 ### `contentEntryDelete`
 
-Soft-delete a CMS Content Entry. Refuses if a Step references it.
+Deletes a content entry. Fails with `CONFLICT` while a step uses it as its layout, or while
+another content entry references it.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 contentEntryDelete(input: ContentEntryDeleteInput!): ContentEntryDeletePayload! @auth
@@ -162,7 +240,9 @@ contentEntryDelete(input: ContentEntryDeleteInput!): ContentEntryDeletePayload!
 
 ### `assetUploadInit`
 
-Initiate an Asset upload — returns a pre-signed PUT URL plus the allocated asset id.
+Starts an asset upload and returns a pre-signed URL to PUT the bytes to. Nothing is stored until
+`assetCommit`.
+Scope: `ORGANIZATION_PROJECTS_UPDATE`.
 
 ```graphql
 assetUploadInit(input: AssetUploadInitInput!): AssetUploadInitPayload! @auth
@@ -170,7 +250,9 @@ assetUploadInit(input: AssetUploadInitInput!): AssetUploadInitPayload! @auth
 
 ### `assetCommit`
 
-Finalise an Asset upload — captures size, MIME, and intrinsic dimensions for images.
+Commits an uploaded file as the asset's current version, recording its size, MIME type and image
+dimensions. Fails when the bytes do not match the claimed content type.
+Scope: `ORGANIZATION_PROJECTS_UPDATE`.
 
 ```graphql
 assetCommit(input: AssetCommitInput!): AssetCommitPayload! @auth
@@ -178,7 +260,9 @@ assetCommit(input: AssetCommitInput!): AssetCommitPayload! @auth
 
 ### `assetDelete`
 
-Soft-delete an Asset. The underlying storage object is removed best-effort.
+Deletes an asset and its stored files. Fails with `CONFLICT` once a publish uses any of its
+versions; content entries that reference it are not checked.
+Scope: `ORGANIZATION_PROJECTS_UPDATE`.
 
 ```graphql
 assetDelete(input: AssetDeleteInput!): AssetDeletePayload! @auth
@@ -189,14 +273,11 @@ assetDelete(input: AssetDeleteInput!): AssetDeletePayload! @auth
 ### `ContentModelCategory`
 
 ```graphql
-"""
-Content Model schema category. Picking a category determines where the
-Content Model surfaces in the dashboard.
-"""
+"""The role of a model, which decides what its entries lay out."""
 enum ContentModelCategory {
-  """Layout configuration for an experience Step."""
+  """The layout of one step inside a flow."""
   STEP_LAYOUT
-  """Layout configuration for an experience Page."""
+  """The layout of a page."""
   PAGE_LAYOUT
 }
 ```
@@ -204,13 +285,9 @@ enum ContentModelCategory {
 ### `ContentBlockCategory`
 
 ```graphql
-"""
-Content Block schema category. Blocks of a given category can only be
-embedded inside Models / Blocks whose schema declares a
-`ContentBlockFieldDefinition` accepting that category.
-"""
+"""The role of a block, which decides which block fields accept it."""
 enum ContentBlockCategory {
-  """A page section (hero, feature list, testimonial, etc.)."""
+  """A page section, such as a hero, a feature list or a testimonial."""
   SECTION
 }
 ```
@@ -218,19 +295,15 @@ enum ContentBlockCategory {
 ### `MigrationWarningType`
 
 ```graphql
-"""
-Kind of warning produced by an auto-migration of dependent Content Entries when a parent Content Model's schema changes.
-"""
+"""What a model schema change did to the data of one content entry."""
 enum MigrationWarningType {
-  """
-  A field was dropped from the schema; entry data for that field has been removed.
-  """
+  """The field left the schema, and its value was removed."""
   FIELD_REMOVED
   """
-  A field's type changed; entry data for that field has been coerced (or set to null if coercion is not possible).
+  The field changed type, and its value could not be converted, so it was removed.
   """
   TYPE_CHANGE
-  """A field was renamed and requires manual migration in the dashboard."""
+  """The field was renamed, and its value needs moving by hand."""
   RENAME_REQUIRED
 }
 ```
@@ -239,33 +312,31 @@ enum MigrationWarningType {
 
 ```graphql
 """
-A workspace-scoped CMS Content Model — the structural schema that
-dependent Content Entries conform to. Changing a Content Model's schema
-auto-migrates dependent entries (see `migrationWarnings` on the
-update payload).
+A reusable schema that sets which fields a content entry can hold. Changing its schema migrates
+the data of its entries.
 """
 type ContentModel {
-  """Unique Content Model identifier."""
+  """The ID of the model."""
   id: ID!
-  """The workspace this Content Model belongs to."""
+  """The workspace that holds the model."""
   workspace: Workspace!
   """
-  Category — determines where this Model surfaces in the dashboard. Null for a general-purpose Content Model with no layout role.
+  The role of the model. Null for general content, which has no layout role.
   """
   category: ContentModelCategory
-  """Display name."""
+  """The name of the model."""
   name: String!
-  """Optional human-readable description."""
+  """The description of the model. Null when it has none."""
   description: String
-  """Stable, human-readable key for SDK consumers."""
+  """The stable identifier of the model. It cannot change."""
   key: String!
-  """The typed schema describing the entries' shape."""
+  """The fields that the model's entries hold."""
   schema: ContentSchema!
-  """Content Entries that instantiate this Content Model."""
+  """The content entries of the model."""
   contentEntries(first: Int, after: String, last: Int, before: String): ContentEntryConnection!
-  """When this Content Model was created."""
+  """When the model was created."""
   createdAt: DateTime!
-  """When this Content Model was last updated."""
+  """When the model last changed."""
   updatedAt: DateTime!
 }
 ```
@@ -273,11 +344,11 @@ type ContentModel {
 ### `ContentModelEdge`
 
 ```graphql
-"""Edge type for `ContentModelConnection`."""
+"""A model in a page of results."""
 type ContentModelEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
-  """The Content Model."""
+  """The model."""
   node: ContentModel!
 }
 ```
@@ -285,17 +356,17 @@ type ContentModelEdge {
 ### `ContentModelConnection`
 
 ```graphql
-"""
-Relay-style connection of Content Models, with both an `edges` list and a flat `nodes` accessor.
-"""
+"""A page of models."""
 type ContentModelConnection {
-  """List of Content Model edges."""
+  """The edges in this page."""
   edges: [ContentModelEdge!]!
-  """Flat list of Content Models, equivalent to `edges[].node`."""
+  """The models in this page."""
   nodes: [ContentModel!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of Content Models."""
+  """
+  The number of models that match `category`. `search` does not narrow it.
+  """
   totalCount: Int!
 }
 ```
@@ -304,34 +375,30 @@ type ContentModelConnection {
 
 ```graphql
 """
-A workspace-scoped CMS Content Block — an embeddable schema fragment for
-use inside Content Models.
-
-WARNING: Unlike Content Models, changing a Content Block's schema does
-NOT auto-migrate dependent Content Entries that embed it. Run
-`workspaceContentEntryValidation` as a pre-publish sanity gate after
-modifying a Content Block schema.
+A reusable schema fragment that you put inside one or more models. Changing its schema does not
+migrate the content entries that embed it; `workspaceContentEntryValidation` finds the entries
+that do not match.
 """
 type ContentBlock {
-  """Unique Content Block identifier."""
+  """The ID of the block."""
   id: ID!
-  """The workspace this Content Block belongs to."""
+  """The workspace that holds the block."""
   workspace: Workspace!
   """
-  Category — restricts which Content Models / Blocks may embed instances of this Block. Null for a general-purpose Content Block with no layout role, which only a `ContentBlockFieldDefinition` that itself sets no category may embed.
+  The role of the block. Null for general content, which has no layout role.
   """
   category: ContentBlockCategory
-  """Display name."""
+  """The name of the block."""
   name: String!
-  """Optional human-readable description."""
+  """The description of the block. Null when it has none."""
   description: String
-  """Stable, human-readable key for SDK consumers."""
+  """The stable identifier of the block. It cannot change."""
   key: String!
-  """The typed schema describing block instances' shape."""
+  """The fields that each instance of the block holds."""
   schema: ContentSchema!
-  """When this Content Block was created."""
+  """When the block was created."""
   createdAt: DateTime!
-  """When this Content Block was last updated."""
+  """When the block last changed."""
   updatedAt: DateTime!
 }
 ```
@@ -339,11 +406,11 @@ type ContentBlock {
 ### `ContentBlockEdge`
 
 ```graphql
-"""Edge type for `ContentBlockConnection`."""
+"""A block in a page of results."""
 type ContentBlockEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
-  """The Content Block."""
+  """The block."""
   node: ContentBlock!
 }
 ```
@@ -351,17 +418,17 @@ type ContentBlockEdge {
 ### `ContentBlockConnection`
 
 ```graphql
-"""
-Relay-style connection of Content Blocks, with both an `edges` list and a flat `nodes` accessor.
-"""
+"""A page of blocks."""
 type ContentBlockConnection {
-  """List of Content Block edges."""
+  """The edges in this page."""
   edges: [ContentBlockEdge!]!
-  """Flat list of Content Blocks, equivalent to `edges[].node`."""
+  """The blocks in this page."""
   nodes: [ContentBlock!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of Content Blocks."""
+  """
+  The number of blocks that match `category`. `search` does not narrow it.
+  """
   totalCount: Int!
 }
 ```
@@ -369,30 +436,24 @@ type ContentBlockConnection {
 ### `ContentEntry`
 
 ```graphql
-"""
-A workspace-scoped CMS Content Entry — an instance of a parent Content
-Model's schema. The `data` field is strongly typed: a single codec
-encodes / decodes the underlying `jsonb` column against the parent
-schema.
-"""
+"""One instance of a model, filled with real values."""
 type ContentEntry {
-  """Unique Content Entry identifier."""
+  """The ID of the content entry."""
   id: ID!
-  """The workspace this Content Entry belongs to."""
+  """The workspace that holds the content entry."""
   workspace: Workspace!
-  """Parent Content Model — defines the schema this entry conforms to."""
+  """The model that the content entry is an instance of."""
   contentModel: ContentModel!
   """
-  Server-derived display name: the value of the first populated
-  single-line-text field in the parent schema, falling back to the entry
-  `id` when none is present.
+  The name that the entries list shows: the first filled single-line text field, or `Untitled`
+  when there is none.
   """
   title: String!
-  """The entry's data, structurally typed against the parent schema."""
+  """The values of the content entry, typed by its model's schema."""
   data: ContentEntryData!
-  """When this Content Entry was created."""
+  """When the content entry was created."""
   createdAt: DateTime!
-  """When this Content Entry was last updated."""
+  """When the content entry last changed."""
   updatedAt: DateTime!
 }
 ```
@@ -400,11 +461,11 @@ type ContentEntry {
 ### `ContentEntryEdge`
 
 ```graphql
-"""Edge type for `ContentEntryConnection`."""
+"""A content entry in a page of results."""
 type ContentEntryEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
-  """The Content Entry."""
+  """The content entry."""
   node: ContentEntry!
 }
 ```
@@ -412,17 +473,15 @@ type ContentEntryEdge {
 ### `ContentEntryConnection`
 
 ```graphql
-"""
-Relay-style connection of Content Entries, with both an `edges` list and a flat `nodes` accessor.
-"""
+"""A page of content entries."""
 type ContentEntryConnection {
-  """List of Content Entry edges."""
+  """The edges in this page."""
   edges: [ContentEntryEdge!]!
-  """Flat list of Content Entries, equivalent to `edges[].node`."""
+  """The content entries in this page."""
   nodes: [ContentEntry!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of Content Entries."""
+  """The number of content entries that match the filters."""
   totalCount: Int!
 }
 ```
@@ -431,53 +490,45 @@ type ContentEntryConnection {
 
 ```graphql
 """
-A project-scoped binary asset (image, video, document) stored in the
-`cms-assets` Supabase Storage bucket.
-
-Lifecycle: `assetUploadInit` reserves an id and returns a pre-signed
-PUT URL; the dashboard uploads directly to storage; `assetCommit`
-finalises the row with `sizeBytes`, `mimeType`, and (for images)
-`width` / `height`. Soft-delete via `assetDelete` — the underlying
-object is removed best-effort.
+A file that your content points at: an image, a video, a document, or HTML. It belongs to a
+project, and each upload of new bytes makes or replaces an asset version.
 """
 type Asset {
-  """Unique Asset identifier. Stable across versions."""
+  """The ID of the asset."""
   id: ID!
-  """The project this Asset belongs to."""
+  """The project that holds the asset."""
   project: Project!
-  """Original file name supplied at upload time."""
+  """The file name given at upload."""
   fileName: String!
   """
-  The Workbench that owns this Asset, when it was authored/uploaded into one. Null for project-level assets.
+  The workbench that owns the asset. Null for an asset in the project's asset library.
   """
   owner: AssetOwner
-  """MIME type, resolved from the current version."""
+  """The MIME type of the current version."""
   mimeType: String!
-  """File size in bytes, resolved from the current version."""
+  """The size of the current version, in bytes."""
   sizeBytes: Int!
   """
-  Intrinsic image width in pixels, resolved from the current version — populated only for image MIME types.
+  The width of the current version, in pixels. Null when it is not an image.
   """
   width: Int
   """
-  Intrinsic image height in pixels, resolved from the current version — populated only for image MIME types.
+  The height of the current version, in pixels. Null when it is not an image.
   """
   height: Int
   """
-  The path inside the `cms-assets` bucket for the current version: `cms-assets/<project>/<asset>/<version>/<file_name>`.
+  The storage path of the current version: `<project>/<asset>/<version>/<file name>`.
   """
   storagePath: String!
-  """
-  The proxy URL the dashboard / SDK can use to fetch the current version's binary.
-  """
+  """The public URL of the current version's file."""
   url: String!
   """
-  The version currently serving this Asset's byte-shaped fields (`url`, `mimeType`, `sizeBytes`, `width`, `height`).
+  The version whose bytes `url`, `mimeType`, `sizeBytes`, `width` and `height` describe.
   """
   currentVersion: AssetVersion!
-  """Every version of this Asset, oldest first."""
+  """Every version of the asset, oldest first."""
   versions: [AssetVersion!]!
-  """When this Asset was created (i.e. when `assetCommit` completed)."""
+  """When the asset was created."""
   createdAt: DateTime!
 }
 ```
@@ -486,37 +537,30 @@ type Asset {
 
 ```graphql
 """
-A single byte-state of an Asset. Immutable versions (flagged at publish) are
-never overwritten — the next edit forks a new version instead of reusing it.
+One file that somebody uploaded for an asset. Once a publish uses a version, the version never
+changes, and the next upload makes a new version.
 """
 type AssetVersion {
-  """Unique AssetVersion identifier."""
+  """The ID of the asset version."""
   id: ID!
-  """MIME type captured at commit time."""
+  """The MIME type of the file."""
   mimeType: String!
-  """File size in bytes."""
+  """The size of the file, in bytes."""
   sizeBytes: Int!
-  """Intrinsic image width in pixels — populated only for image MIME types."""
+  """The width of the file, in pixels. Null when it is not an image."""
   width: Int
-  """
-  Intrinsic image height in pixels — populated only for image MIME types.
-  """
+  """The height of the file, in pixels. Null when it is not an image."""
   height: Int
-  """
-  True once this version has been referenced by a publish — never overwritten again.
-  """
+  """Whether a publish uses the version, so that it never changes."""
   isImmutable: Boolean!
   """
-  Lowercase hex SHA-256 of this version's stored bytes, computed by the server
-  during `assetCommit`. Null for versions committed before content hashing, and
-  while an upload that overwrites this version in place is not yet committed.
+  The lowercase hex SHA-256 of the stored bytes. Null when no hash was recorded, and while an
+  upload that replaces this version is not committed.
   """
   sha256: String
-  """
-  The proxy URL the dashboard / SDK can use to fetch this version's binary.
-  """
+  """The public URL of the version's file."""
   url: String!
-  """When this version was created."""
+  """When the version was created."""
   createdAt: DateTime!
 }
 ```
@@ -524,11 +568,11 @@ type AssetVersion {
 ### `AssetOwner`
 
 ```graphql
-"""Identifies the Workbench that owns an Asset."""
+"""The workbench that owns an asset."""
 type AssetOwner {
-  """The owner kind, currently always `"workbench"`."""
+  """The kind of owner. Always `"workbench"`."""
   type: String!
-  """The owning Workbench id."""
+  """The ID of the workbench."""
   id: String!
 }
 ```
@@ -536,11 +580,11 @@ type AssetOwner {
 ### `AssetEdge`
 
 ```graphql
-"""Edge type for `AssetConnection`."""
+"""An asset in a page of results."""
 type AssetEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
-  """The Asset."""
+  """The asset."""
   node: Asset!
 }
 ```
@@ -548,17 +592,15 @@ type AssetEdge {
 ### `AssetConnection`
 
 ```graphql
-"""
-Relay-style connection of Assets, with both an `edges` list and a flat `nodes` accessor.
-"""
+"""A page of assets."""
 type AssetConnection {
-  """List of Asset edges."""
+  """The edges in this page."""
   edges: [AssetEdge!]!
-  """Flat list of Assets, equivalent to `edges[].node`."""
+  """The assets in this page."""
   nodes: [Asset!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of Assets."""
+  """The number of assets that match the filters."""
   totalCount: Int!
 }
 ```
@@ -567,19 +609,17 @@ type AssetConnection {
 
 ```graphql
 """
-A single Content-Entry-migration warning produced when a parent Content
-Model's schema changes and dependent entries' data needed to be
-auto-coerced or dropped.
+A change that a model schema update made to the data of one content entry.
 """
 type MigrationWarning {
-  """The Content Entry whose data was affected."""
+  """The ID of the content entry whose data changed."""
   contentEntryId: ID!
-  """JSON-Pointer-style path into the entry data (e.g. `$.title`)."""
+  """The path of the field in the entry data, such as `$.title`."""
   fieldPath: String!
-  """Kind of warning."""
+  """What happened to the value."""
   warningType: MigrationWarningType!
   """
-  Stringified previous value, when applicable (truncated for large blobs).
+  The value before the change, cut to 80 characters. Null when the value was null.
   """
   oldValue: String
 }
@@ -589,24 +629,17 @@ type MigrationWarning {
 
 ```graphql
 """
-Result of validating every Content Entry in a workspace against its
-parent Content Model schema (recursively walking embedded Content Block
-instances).
-
-Useful as a pre-publish sanity gate, especially after a Content Block
-schema change (which does NOT auto-migrate dependent Content Entries
-the way Content Model schema changes do).
+The result of `workspaceContentEntryValidation`. It checks each content entry against its model's
+schema, including embedded blocks.
 """
 type WorkspaceContentEntryValidationPayload {
-  """Total Content Entry rows visited."""
+  """The number of content entries checked."""
   totalCount: Int!
-  """Rows whose `data` blob conforms cleanly to its Content Model schema."""
+  """The number of content entries that match their schema."""
   validCount: Int!
-  """Rows with at least one validation error."""
+  """The number of content entries with at least one validation error."""
   invalidCount: Int!
-  """
-  Per-Content-Entry outcomes, in DB-order (matches `contentEntries` query ordering).
-  """
+  """The outcome for each content entry, oldest first."""
   outcomes: [ContentEntryValidationOutcome!]!
 }
 ```
@@ -614,31 +647,23 @@ type WorkspaceContentEntryValidationPayload {
 ### `ContentEntryValidationOutcome`
 
 ```graphql
-"""A single Content Entry's validation outcome."""
+"""The validation outcome of one content entry."""
 type ContentEntryValidationOutcome {
-  """
-  Identifier for the Content Entry — always present, even when `contentEntry` is null due to a soft-delete race.
-  """
+  """The ID of the content entry."""
   contentEntryId: ID!
-  """
-  Identifier for the parent Content Model — always present, even when `contentModel` is null due to a soft-delete race.
-  """
+  """The ID of the content entry's model."""
   contentModelId: ID!
-  """
-  The Content Entry that was validated. Null if it was concurrently soft-deleted.
-  """
+  """The content entry. Null when it was deleted during the check."""
   contentEntry: ContentEntry
-  """The parent Content Model. Null if it was concurrently soft-deleted."""
+  """The content entry's model. Null when it was deleted during the check."""
   contentModel: ContentModel
   """
-  Snapshot of the parent Content Model name at validation time — non-null even if the parent was concurrently soft-deleted.
+  The name of the model at the time of the check, or `(unknown)` when the model is missing.
   """
   contentModelName: String!
-  """
-  Whether the Content Entry data conforms to the parent Content Model schema.
-  """
+  """Whether the content entry matches its model's schema."""
   valid: Boolean!
-  """Per-field validation errors. Empty when `valid` is true."""
+  """The validation errors. Empty when `valid` is true."""
   errors: [ContentEntryValidationError!]!
 }
 ```
@@ -646,15 +671,13 @@ type ContentEntryValidationOutcome {
 ### `ContentEntryValidationError`
 
 ```graphql
-"""
-A single Content Entry validation error pinned to a path inside the `data` blob.
-"""
+"""A report that one field in a content entry does not match its schema."""
 type ContentEntryValidationError {
   """
-  JSON-Pointer-style path inside the Content Entry data, e.g. `$.title` or `$.sections[0].headline`.
+  The path of the field in the entry data, such as `$.sections[0].headline`.
   """
   path: String!
-  """Human-readable error message."""
+  """A human-readable description of the error."""
   message: String!
 }
 ```
@@ -662,21 +685,21 @@ type ContentEntryValidationError {
 ### `ContentModelCreateInput`
 
 ```graphql
-"""Input for `contentModelCreate`."""
+"""The input of `contentModelCreate`."""
 input ContentModelCreateInput {
-  """Workspace ID to create the Content Model in."""
+  """The ID of the workspace to create the model in."""
   workspaceId: ID!
   """
-  Category — determines where the Model surfaces in the dashboard. Omit for a general-purpose Content Model with no layout role.
+  The role of the model. Omit it for general content. It cannot change later.
   """
   category: ContentModelCategory
-  """Display name."""
+  """The name of the model. It must not be blank."""
   name: String!
-  """Optional human-readable description."""
+  """The description of the model."""
   description: String
-  """Stable, human-readable key for SDK consumers."""
+  """The stable identifier of the model. It cannot change later."""
   key: String!
-  """Initial schema."""
+  """The fields that the model's entries hold."""
   schema: ContentSchemaInput!
 }
 ```
@@ -684,9 +707,9 @@ input ContentModelCreateInput {
 ### `ContentModelCreatePayload`
 
 ```graphql
-"""Payload returned by `contentModelCreate`."""
+"""The result of `contentModelCreate`."""
 type ContentModelCreatePayload {
-  """The created Content Model."""
+  """The created model."""
   contentModel: ContentModel
 }
 ```
@@ -694,17 +717,15 @@ type ContentModelCreatePayload {
 ### `ContentModelUpdateInput`
 
 ```graphql
-"""Input for `contentModelUpdate`. Omit a field to leave it unchanged."""
+"""The input of `contentModelUpdate`. Omit a field to keep its value."""
 input ContentModelUpdateInput {
-  """Content Model ID."""
+  """The ID of the model. Required."""
   id: ID!
-  """New display name."""
+  """The new name. It must not be blank."""
   name: String
-  """New description. Omit to leave unchanged."""
+  """The new description."""
   description: String
-  """
-  New schema. Schema changes auto-migrate dependent Content Entries; affected paths are returned in `migrationWarnings`.
-  """
+  """The new schema. The data of the model's entries migrates to it."""
   schema: ContentSchemaInput
 }
 ```
@@ -712,16 +733,12 @@ input ContentModelUpdateInput {
 ### `ContentModelUpdatePayload`
 
 ```graphql
-"""
-Payload returned by `contentModelUpdate`. `migrationWarnings` lists
-every per-Content-Entry coercion or field-removal performed when the
-schema change required it.
-"""
+"""The result of `contentModelUpdate`."""
 type ContentModelUpdatePayload {
-  """The updated Content Model."""
+  """The updated model."""
   contentModel: ContentModel
   """
-  Per-Content-Entry warnings emitted when the schema change dropped or coerced fields.
+  The values that the schema change removed from content entries. Empty when none.
   """
   migrationWarnings: [MigrationWarning!]!
 }
@@ -730,11 +747,9 @@ type ContentModelUpdatePayload {
 ### `ContentModelDeleteInput`
 
 ```graphql
-"""
-Input for `contentModelDelete`. Refused if dependent Content Entry rows still exist.
-"""
+"""The input of `contentModelDelete`."""
 input ContentModelDeleteInput {
-  """Content Model ID."""
+  """The ID of the model."""
   id: ID!
 }
 ```
@@ -742,9 +757,9 @@ input ContentModelDeleteInput {
 ### `ContentModelDeletePayload`
 
 ```graphql
-"""Payload returned by `contentModelDelete`."""
+"""The result of `contentModelDelete`."""
 type ContentModelDeletePayload {
-  """ID of the deleted Content Model."""
+  """The ID of the deleted model."""
   contentModelId: ID
 }
 ```
@@ -752,21 +767,21 @@ type ContentModelDeletePayload {
 ### `ContentBlockCreateInput`
 
 ```graphql
-"""Input for `contentBlockCreate`."""
+"""The input of `contentBlockCreate`."""
 input ContentBlockCreateInput {
-  """Workspace ID to create the Content Block in."""
+  """The ID of the workspace to create the block in."""
   workspaceId: ID!
   """
-  Category — restricts where instances of this Block may be embedded. Omit for a general-purpose Content Block with no layout role.
+  The role of the block. Omit it for general content. It cannot change later.
   """
   category: ContentBlockCategory
-  """Display name."""
+  """The name of the block. It must not be blank."""
   name: String!
-  """Optional human-readable description."""
+  """The description of the block."""
   description: String
-  """Stable, human-readable key for SDK consumers."""
+  """The stable identifier of the block. It cannot change later."""
   key: String!
-  """Initial schema."""
+  """The fields that each instance of the block holds."""
   schema: ContentSchemaInput!
 }
 ```
@@ -774,9 +789,9 @@ input ContentBlockCreateInput {
 ### `ContentBlockCreatePayload`
 
 ```graphql
-"""Payload returned by `contentBlockCreate`."""
+"""The result of `contentBlockCreate`."""
 type ContentBlockCreatePayload {
-  """The created Content Block."""
+  """The created block."""
   contentBlock: ContentBlock
 }
 ```
@@ -784,16 +799,16 @@ type ContentBlockCreatePayload {
 ### `ContentBlockUpdateInput`
 
 ```graphql
-"""Input for `contentBlockUpdate`. Omit a field to leave it unchanged."""
+"""The input of `contentBlockUpdate`. Omit a field to keep its value."""
 input ContentBlockUpdateInput {
-  """Content Block ID."""
+  """The ID of the block. Required."""
   id: ID!
-  """New display name."""
+  """The new name. It must not be blank."""
   name: String
-  """New description. Omit to leave unchanged."""
+  """The new description."""
   description: String
   """
-  New schema. WARNING: changing a Block schema does NOT auto-migrate dependent Content Entries — run `workspaceContentEntryValidation` to find drift.
+  The new schema. The data of content entries that embed the block does not migrate.
   """
   schema: ContentSchemaInput
 }
@@ -802,9 +817,9 @@ input ContentBlockUpdateInput {
 ### `ContentBlockUpdatePayload`
 
 ```graphql
-"""Payload returned by `contentBlockUpdate`."""
+"""The result of `contentBlockUpdate`."""
 type ContentBlockUpdatePayload {
-  """The updated Content Block."""
+  """The updated block."""
   contentBlock: ContentBlock
 }
 ```
@@ -812,9 +827,9 @@ type ContentBlockUpdatePayload {
 ### `ContentBlockDeleteInput`
 
 ```graphql
-"""Input for `contentBlockDelete`."""
+"""The input of `contentBlockDelete`."""
 input ContentBlockDeleteInput {
-  """Content Block ID."""
+  """The ID of the block."""
   id: ID!
 }
 ```
@@ -822,9 +837,9 @@ input ContentBlockDeleteInput {
 ### `ContentBlockDeletePayload`
 
 ```graphql
-"""Payload returned by `contentBlockDelete`."""
+"""The result of `contentBlockDelete`."""
 type ContentBlockDeletePayload {
-  """ID of the deleted Content Block."""
+  """The ID of the deleted block."""
   contentBlockId: ID
 }
 ```
@@ -832,13 +847,14 @@ type ContentBlockDeletePayload {
 ### `ContentEntryCreateInput`
 
 ```graphql
-"""Input for `contentEntryCreate`."""
+"""The input of `contentEntryCreate`."""
 input ContentEntryCreateInput {
+  """The ID of the model whose schema the data must match."""
+  contentModelId: ID!
   """
-  Parent Content Model id — the entry's data must conform to this Model's schema.
+  The values of the content entry. Empty data makes an empty entry; data with any value must hold
+  every required field.
   """
-  contentModelId: ID!
-  """The entry's data, structurally typed against the parent schema."""
   data: ContentEntryDataInput!
 }
 ```
@@ -846,9 +862,9 @@ input ContentEntryCreateInput {
 ### `ContentEntryCreatePayload`
 
 ```graphql
-"""Payload returned by `contentEntryCreate`."""
+"""The result of `contentEntryCreate`."""
 type ContentEntryCreatePayload {
-  """The created Content Entry."""
+  """The created content entry."""
   contentEntry: ContentEntry
 }
 ```
@@ -856,13 +872,14 @@ type ContentEntryCreatePayload {
 ### `ContentEntryUpdateInput`
 
 ```graphql
-"""
-Input for `contentEntryUpdate`. The entire `data` blob is replaced; partial updates are not supported.
-"""
+"""The input of `contentEntryUpdate`. Every field is required."""
 input ContentEntryUpdateInput {
-  """Content Entry ID."""
+  """The ID of the content entry."""
   id: ID!
-  """New entry data — must conform to the parent Content Model's schema."""
+  """
+  The new values of the content entry. They replace all of its data and must hold every required
+  field.
+  """
   data: ContentEntryDataInput!
 }
 ```
@@ -870,9 +887,9 @@ input ContentEntryUpdateInput {
 ### `ContentEntryUpdatePayload`
 
 ```graphql
-"""Payload returned by `contentEntryUpdate`."""
+"""The result of `contentEntryUpdate`."""
 type ContentEntryUpdatePayload {
-  """The updated Content Entry."""
+  """The updated content entry."""
   contentEntry: ContentEntry
 }
 ```
@@ -880,9 +897,9 @@ type ContentEntryUpdatePayload {
 ### `ContentEntryDeleteInput`
 
 ```graphql
-"""Input for `contentEntryDelete`. Refused if a Step references it."""
+"""The input of `contentEntryDelete`."""
 input ContentEntryDeleteInput {
-  """Content Entry ID."""
+  """The ID of the content entry."""
   id: ID!
 }
 ```
@@ -890,9 +907,9 @@ input ContentEntryDeleteInput {
 ### `ContentEntryDeletePayload`
 
 ```graphql
-"""Payload returned by `contentEntryDelete`."""
+"""The result of `contentEntryDelete`."""
 type ContentEntryDeletePayload {
-  """ID of the deleted Content Entry."""
+  """The ID of the deleted content entry."""
   contentEntryId: ID
 }
 ```
@@ -901,43 +918,35 @@ type ContentEntryDeletePayload {
 
 ```graphql
 """
-Input for `assetUploadInit` — reserve an Asset id and obtain a pre-signed PUT
-URL. Passing `assetId` targets an existing Asset for a new write: the write
-overwrites the current version in place while it is mutable, or forks a new
-version once the current version has been published (copy-on-write).
-
-Passing `sha256` on a new project-level upload (no `assetId`, no `workbenchId`)
-deduplicates it: when a non-deleted, project-level (not Workbench-owned) Asset
-in the same project already has a version with those bytes, the payload returns that Asset and version with
-`deduplicated: true` and no `uploadUrl`, and there is nothing to upload or
-commit.
+The input of `assetUploadInit`. With `assetId`, the upload replaces the current version while no
+publish uses it, and makes a new version once one does.
 """
 input AssetUploadInitInput {
-  """Project to upload the Asset into."""
+  """The ID of the project to upload the asset into."""
   projectId: ID!
   """
-  Original file name. Stored verbatim — used for display and in the storage path.
+  The file name. It must not contain `/` or `\`. Ignored when `path` is given.
   """
   fileName: String!
-  """
-  MIME type the dashboard expects to upload. Must match the uploaded bytes' content-type.
-  """
+  """The MIME type of the bytes to upload."""
   contentType: String!
   """
-  Targets an existing Asset for a new write (overwrite or fork). Omit to create a new Asset.
+  The ID of an existing asset to upload new bytes for. Omit it to create an asset.
   """
   assetId: ID
-  """The Workbench this upload belongs to."""
+  """
+  The ID of the workbench the upload belongs to. It must be in the same project.
+  """
   workbenchId: ID
   """
-  Logical path within the Workbench (for example `drafts/outline-v1.md`).
-  When given, the server derives `fileName` from the segment after the last `/`.
+  The path of the file in the workbench, such as `drafts/outline-v1.md`. The file name is the part
+  after the last `/`.
   """
   path: String
   """
-  Hex SHA-256 of the bytes the client will upload (64 characters, either case).
-  Enables deduplication for new project-level uploads. Pass the same value to
-  `assetCommit`, which rejects bytes that hash differently.
+  The hex SHA-256 of the bytes to upload, 64 characters in either case. On a new upload with no
+  `assetId` and no `workbenchId`, an asset-library asset that already holds these bytes is
+  returned.
   """
   sha256: String
 }
@@ -947,32 +956,29 @@ input AssetUploadInitInput {
 
 ```graphql
 """
-Payload returned by `assetUploadInit`.
-
-When `deduplicated` is false, PUT the bytes to `uploadUrl` and then call
-`assetCommit` with `assetId`, `versionId` and `storagePath`. When it is true,
-`assetId` and `versionId` name an existing committed version whose bytes match
-the declared `sha256`; reference them directly, with no upload and no commit.
+The result of `assetUploadInit`. When `deduplicated` is false, PUT the bytes to `uploadUrl`, then
+call `assetCommit`; when it is true, the existing version holds the bytes and needs no upload or
+commit.
 """
 type AssetUploadInitPayload {
   """
-  Pre-signed PUT URL the client uploads to. Null when `deduplicated` is true.
+  The pre-signed URL to PUT the bytes to. Null when `deduplicated` is true.
   """
   uploadUrl: String
   """
-  The asset id — pre-allocated for a new Asset, the `assetId` passed in for an existing one, or the Asset owning the matching version when deduplicated. The dashboard MUST pass this to `assetCommit` when it uploads.
+  The ID of the asset: a new ID, the `assetId` given, or the asset that holds matching bytes.
   """
   assetId: ID!
   """
-  The version id this upload targets, or the matching existing version when deduplicated. The dashboard MUST pass this to `assetCommit` when it uploads.
+  The ID of the version that the upload writes, or of the existing version that matches.
   """
   versionId: ID!
   """
-  Storage path the URL writes to (echoed back to the commit step), or the matching version's path when deduplicated.
+  The storage path that the upload writes to, or the path of the matching version.
   """
   storagePath: String!
   """
-  True when the project already holds the declared bytes and nothing needs uploading.
+  Whether the project already holds the bytes, so nothing needs uploading.
   """
   deduplicated: Boolean!
 }
@@ -981,34 +987,29 @@ type AssetUploadInitPayload {
 ### `AssetCommitInput`
 
 ```graphql
-"""
-Input for `assetCommit` — finalise an upload by recording `sizeBytes`, `mimeType`, and intrinsic dimensions.
-"""
+"""The input of `assetCommit`."""
 input AssetCommitInput {
-  """Project the Asset belongs to."""
+  """The ID of the project that holds the asset."""
   projectId: ID!
-  """Asset id reserved by `assetUploadInit`."""
+  """The ID of the asset that `assetUploadInit` returned."""
   assetId: ID!
-  """Version id reserved by `assetUploadInit`."""
+  """The ID of the version that `assetUploadInit` returned."""
   versionId: ID!
-  """Original file name (matches the `assetUploadInit` value)."""
+  """The file name given to `assetUploadInit`."""
   fileName: String!
-  """Storage path returned by `assetUploadInit`."""
+  """The storage path that `assetUploadInit` returned."""
   storagePath: String!
   """
-  The Workbench this upload belongs to. Recorded as the Asset's owner only when the Asset document is first created.
+  The ID of the workbench the upload belongs to. It becomes the owner of a new asset only.
   """
   workbenchId: ID
   """
-  Logical path within the Workbench (for example `drafts/outline-v1.md`).
-  When given with `workbenchId`, stored on `workbench_assets.path`; `fileName` is
-  derived from the segment after the last `/` when omitted.
+  The path of the file in the workbench, such as `drafts/outline-v1.md`. It applies only with
+  `workbenchId`.
   """
   path: String
   """
-  Hex SHA-256 the client declared to `assetUploadInit`. When given, the commit
-  returns a `HASH_MISMATCH` user error, and records no version, if the stored
-  bytes hash to anything else.
+  The hex SHA-256 given to `assetUploadInit`. Bytes that hash differently fail the commit.
   """
   sha256: String
 }
@@ -1017,13 +1018,11 @@ input AssetCommitInput {
 ### `AssetCommitPayload`
 
 ```graphql
-"""Payload returned by `assetCommit`."""
+"""The result of `assetCommit`."""
 type AssetCommitPayload {
-  """
-  The committed Asset, now ready to be referenced from Content Entry data. Null when a `userError` was returned.
-  """
+  """The committed asset. Null when the commit failed with a user error."""
   asset: Asset
-  """Errors that stopped the commit. Empty on success."""
+  """The errors that stopped the commit. Empty on success."""
   userErrors: [AssetCommitUserError!]!
 }
 ```
@@ -1031,9 +1030,9 @@ type AssetCommitPayload {
 ### `AssetCommitErrorCode`
 
 ```graphql
-"""Machine-readable error codes for `assetCommit`."""
+"""The reason an `assetCommit` failed."""
 enum AssetCommitErrorCode {
-  """The stored bytes do not hash to the `sha256` given in the input."""
+  """The stored bytes do not hash to the `sha256` in the input."""
   HASH_MISMATCH
 }
 ```
@@ -1041,13 +1040,15 @@ enum AssetCommitErrorCode {
 ### `AssetCommitUserError`
 
 ```graphql
-"""User-facing error for `assetCommit`."""
+"""An error that stopped an `assetCommit`."""
 type AssetCommitUserError {
-  """Path to the offending input field, if applicable."""
+  """
+  The path to the input field that caused the error. Null when no field did.
+  """
   field: [String!]
-  """Human-readable error message."""
+  """A human-readable description of the error."""
   message: String!
-  """Machine-readable error code."""
+  """The reason for the error."""
   code: AssetCommitErrorCode!
 }
 ```
@@ -1055,11 +1056,9 @@ type AssetCommitUserError {
 ### `AssetDeleteInput`
 
 ```graphql
-"""
-Input for `assetDelete` — soft-deletes the Asset row. The underlying storage object is removed best-effort.
-"""
+"""The input of `assetDelete`."""
 input AssetDeleteInput {
-  """Asset ID."""
+  """The ID of the asset."""
   id: ID!
 }
 ```
@@ -1067,9 +1066,9 @@ input AssetDeleteInput {
 ### `AssetDeletePayload`
 
 ```graphql
-"""Payload returned by `assetDelete`."""
+"""The result of `assetDelete`."""
 type AssetDeletePayload {
-  """ID of the deleted Asset."""
+  """The ID of the deleted asset."""
   assetId: ID
 }
 ```
@@ -1077,15 +1076,13 @@ type AssetDeletePayload {
 ### `ContentBlockSortKeys`
 
 ```graphql
-"""
-Sort keys for `contentBlocks(...)`. Pair with `reverse: true` to flip the order.
-"""
+"""The order of `contentBlocks`."""
 enum ContentBlockSortKeys {
-  """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
 }
 ```
@@ -1093,15 +1090,13 @@ enum ContentBlockSortKeys {
 ### `ContentModelSortKeys`
 
 ```graphql
-"""
-Sort keys for `contentModels(...)`. Pair with `reverse: true` to flip the order.
-"""
+"""The order of `contentModels`."""
 enum ContentModelSortKeys {
-  """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
 }
 ```
@@ -1109,13 +1104,11 @@ enum ContentModelSortKeys {
 ### `ContentEntrySortKeys`
 
 ```graphql
-"""
-Sort keys for `contentEntries(...)`. Entries have no name; pair with `reverse: true` to flip the order.
-"""
+"""The order of `contentEntries`."""
 enum ContentEntrySortKeys {
-  """Sort by `createdAt`."""
+  """By creation time, oldest first."""
   CREATED_AT
-  """Sort by `updatedAt`."""
+  """By last change, oldest first."""
   UPDATED_AT
 }
 ```
@@ -1123,13 +1116,11 @@ enum ContentEntrySortKeys {
 ### `AssetSortKeys`
 
 ```graphql
-"""
-Sort keys for `assets(...)`. Pair with `reverse: true` to flip the order.
-"""
+"""The order of `assets`."""
 enum AssetSortKeys {
-  """Sort by `fileName` (alphabetical)."""
+  """By file name, A to Z."""
   NAME
-  """Sort by `createdAt` (upload time)."""
+  """By upload time, oldest first."""
   CREATED_AT
 }
 ```
@@ -1138,7 +1129,7 @@ enum AssetSortKeys {
 
 ```graphql
 """
-A media-type bucket for browsing the asset library, matched against the current version's MIME type.
+A media type group of assets, matched against the MIME type of the current version.
 """
 enum AssetKind {
   """`image/*`."""
@@ -1147,9 +1138,9 @@ enum AssetKind {
   VIDEO
   """`audio/*`."""
   AUDIO
-  """Anything that is not an image, video, audio, or recognised archive."""
+  """Any file that is not an image, video, audio or archive."""
   DOCUMENT
-  """A recognised archive type (zip, rar, gzip, 7z, tar)."""
+  """An archive: zip, rar, gzip, 7z or tar."""
   ARCHIVE
 }
 ```