picked 0.0.101 → 0.0.102-next.2

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

@@ -6,13 +6,15 @@ generated: true
 
 # Workbench schema
 
-The operations and types that `workbench.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.
 
 ## Mutations
 
 ### `workbenchAssetImport`
 
-Imports an Asset owned elsewhere into a Workbench, creating an `IMPORTED` membership. Removing the import (`workbenchAssetRemove`) drops only the join, never the Asset.
+Imports an asset owned elsewhere into a workbench as `IMPORTED`. The asset's owner does not
+change.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 workbenchAssetImport(input: WorkbenchAssetImportInput!): WorkbenchAssetImportPayload! @auth
@@ -20,7 +22,8 @@ workbenchAssetImport(input: WorkbenchAssetImportInput!): WorkbenchAssetImportPay
 
 ### `workbenchAssetAdoptOwned`
 
-Adopts an existing project-library Asset as `OWNED` by a Workbench, transferring the Asset's ownership. Used when a Create-Page upload is bound to its Workbench after the Workbench is created.
+Moves the ownership of an asset-library asset to a workbench, as `OWNED`.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 workbenchAssetAdoptOwned(input: WorkbenchAssetAdoptOwnedInput!): WorkbenchAssetAdoptOwnedPayload! @auth
@@ -28,7 +31,9 @@ workbenchAssetAdoptOwned(input: WorkbenchAssetAdoptOwnedInput!): WorkbenchAssetA
 
 ### `workbenchAssetRemove`
 
-Removes an Asset's membership from a Workbench. If the membership was `OWNED`, the Asset is also soft-deleted; if `IMPORTED`, only the join is dropped.
+Removes an asset from a workbench. Removing an `OWNED` asset also deletes it, which needs
+`ORGANIZATION_PROJECTS_UPDATE` and fails once a publish uses the asset.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 workbenchAssetRemove(input: WorkbenchAssetRemoveInput!): WorkbenchAssetRemovePayload! @auth
@@ -39,14 +44,14 @@ workbenchAssetRemove(input: WorkbenchAssetRemoveInput!): WorkbenchAssetRemovePay
 ### `WorkbenchAssetRelationship`
 
 ```graphql
-"""How an Asset relates to the Workbench it is joined to."""
+"""How an asset belongs to a workbench."""
 enum WorkbenchAssetRelationship {
   """
-  Authored or uploaded directly into this Workbench. Soft-deleted when removed.
+  Uploaded into the workbench, which owns it. Removing it deletes the asset.
   """
   OWNED
   """
-  A reference to an Asset owned elsewhere (for example a Design System's DESIGN.md). Removing it drops only the join.
+  Owned elsewhere, such as a design system's Markdown file. Removing it keeps the asset.
   """
   IMPORTED
 }
@@ -55,12 +60,12 @@ enum WorkbenchAssetRelationship {
 ### `WorkbenchOwner`
 
 ```graphql
-"""Identifies the logical entity a Workbench belongs to."""
+"""The experience or design system that a workbench belongs to."""
 type WorkbenchOwner {
-  """The owner kind: `"experience"` or `"design_system"`."""
+  """The kind of owner: `"experience"` or `"design_system"`."""
   type: String!
   """
-  The owner's stable cross-workspace reference: an Experience's `key`, or a Design System's `id`.
+  The stable reference of the owner: an experience's `key`, or a design system's `id`.
   """
   ref: String!
 }
@@ -69,20 +74,16 @@ type WorkbenchOwner {
 ### `WorkbenchAsset`
 
 ```graphql
-"""One Asset's membership in a Workbench."""
+"""One asset in a workbench."""
 type WorkbenchAsset {
-  """
-  Whether this Asset is owned by the Workbench or imported from elsewhere.
-  """
+  """Whether the workbench owns the asset or imports it."""
   relationship: WorkbenchAssetRelationship!
-  """
-  The logical path of this Asset within the Workbench, if one was assigned at upload time.
-  """
+  """The path of the asset in the workbench. Null when none was given."""
   path: String
-  """The Asset."""
+  """The asset."""
   asset: Asset!
   """
-  The Design System this Asset was imported from, when it is a Design System's file; null otherwise.
+  The design system whose file the asset is. Null unless it is an imported design system file.
   """
   sourceDesignSystem: DesignSystem
 }
@@ -91,11 +92,11 @@ type WorkbenchAsset {
 ### `WorkbenchAssetEdge`
 
 ```graphql
-"""Edge type for `WorkbenchAssetConnection`."""
+"""A workbench asset in a page of results."""
 type WorkbenchAssetEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
-  """The Workbench-Asset membership."""
+  """The workbench asset."""
   node: WorkbenchAsset!
 }
 ```
@@ -103,21 +104,15 @@ type WorkbenchAssetEdge {
 ### `WorkbenchAssetConnection`
 
 ```graphql
-"""
-Relay-style connection of Workbench-Asset memberships, with both an `edges` list and a flat `nodes` accessor.
-"""
+"""A page of workbench assets."""
 type WorkbenchAssetConnection {
-  """List of Workbench-Asset membership edges."""
+  """The edges in this page."""
   edges: [WorkbenchAssetEdge!]!
-  """
-  Flat list of Workbench-Asset memberships, equivalent to `edges[].node`.
-  """
+  """The workbench assets in this page."""
   nodes: [WorkbenchAsset!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """
-  Total number of memberships in this Workbench, optionally filtered by `relationship`.
-  """
+  """The number of assets in the workbench that match `relationship`."""
   totalCount: Int!
 }
 ```
@@ -126,24 +121,17 @@ type WorkbenchAssetConnection {
 
 ```graphql
 """
-A cross-workspace working directory for a logical entity (an Experience or a
-Design System), associated by `(project, ownerType, ownerRef)`. A Workbench is
-NOT scoped to a workspace version, so one Workbench serves every workspace of
-a project that shares the owner reference — including duplicates, since
-workspace duplication preserves an Experience's `key`.
+A working folder of assets for one experience or design system. It is not tied to a workspace:
+every workspace of the project whose owner has the same reference shares it, duplicates included.
 """
 type Workbench {
-  """Unique Workbench identifier."""
+  """The ID of the workbench."""
   id: ID!
-  """The logical entity this Workbench belongs to."""
+  """The experience or design system the workbench belongs to."""
   owner: WorkbenchOwner!
-  """
-  The Assets joined to this Workbench, each carrying its `relationship` and logical `path`.
-  """
+  """The assets in the workbench."""
   assets(
-    """
-    Filter to only `OWNED` or only `IMPORTED` memberships. Omit to return both.
-    """
+    """The relationship to filter by. Omit it for both."""
     relationship: WorkbenchAssetRelationship
     first: Int
     after: String
@@ -156,7 +144,8 @@ type Workbench {
 ```graphql
 extend type Experience {
   """
-  This Experience's Workbench, resolved (and created on first access) by its stable `key`.
+  The workbench of the experience, found by its `key`. Reading it creates the workbench when none
+  exists, and needs `ORGANIZATION_WORKSPACE_UPDATE`.
   """
   workbench: Workbench!
 }
@@ -167,7 +156,8 @@ extend type Experience {
 ```graphql
 extend type DesignSystem {
   """
-  This Design System's Workbench, resolved (and created on first access) by its `id`.
+  The workbench of the design system. Reading it creates the workbench when none exists, and needs
+  `ORGANIZATION_WORKSPACE_UPDATE`.
   """
   workbench: Workbench!
 }
@@ -176,11 +166,11 @@ extend type DesignSystem {
 ### `WorkbenchAssetImportInput`
 
 ```graphql
-"""Input for `workbenchAssetImport`."""
+"""The input of `workbenchAssetImport`."""
 input WorkbenchAssetImportInput {
-  """The Workbench to import into."""
+  """The ID of the workbench to import into."""
   workbenchId: ID!
-  """The Asset to import, owned elsewhere."""
+  """The ID of the asset to import."""
   assetId: ID!
 }
 ```
@@ -188,9 +178,9 @@ input WorkbenchAssetImportInput {
 ### `WorkbenchAssetImportPayload`
 
 ```graphql
-"""Payload returned by `workbenchAssetImport`."""
+"""The result of `workbenchAssetImport`."""
 type WorkbenchAssetImportPayload {
-  """The newly created `IMPORTED` membership."""
+  """The imported workbench asset."""
   workbenchAsset: WorkbenchAsset!
 }
 ```
@@ -198,15 +188,15 @@ type WorkbenchAssetImportPayload {
 ### `WorkbenchAssetAdoptOwnedInput`
 
 ```graphql
-"""Input for `workbenchAssetAdoptOwned`."""
+"""The input of `workbenchAssetAdoptOwned`."""
 input WorkbenchAssetAdoptOwnedInput {
-  """The Workbench that should take ownership of the Asset."""
+  """The ID of the workbench that takes ownership."""
   workbenchId: ID!
   """
-  The project-library Asset to adopt as `OWNED`, transferring its ownership to the Workbench.
+  The ID of the asset, in the workbench's project and not owned by another workbench.
   """
   assetId: ID!
-  """Optional logical path to assign the membership within the Workbench."""
+  """The path of the asset in the workbench."""
   path: String
 }
 ```
@@ -214,9 +204,9 @@ input WorkbenchAssetAdoptOwnedInput {
 ### `WorkbenchAssetAdoptOwnedPayload`
 
 ```graphql
-"""Payload returned by `workbenchAssetAdoptOwned`."""
+"""The result of `workbenchAssetAdoptOwned`."""
 type WorkbenchAssetAdoptOwnedPayload {
-  """The `OWNED` membership after adoption."""
+  """The owned workbench asset."""
   workbenchAsset: WorkbenchAsset!
 }
 ```
@@ -224,11 +214,11 @@ type WorkbenchAssetAdoptOwnedPayload {
 ### `WorkbenchAssetRemoveInput`
 
 ```graphql
-"""Input for `workbenchAssetRemove`."""
+"""The input of `workbenchAssetRemove`."""
 input WorkbenchAssetRemoveInput {
-  """The Workbench to remove the Asset from."""
+  """The ID of the workbench to remove the asset from."""
   workbenchId: ID!
-  """The Asset to remove."""
+  """The ID of the asset to remove."""
   assetId: ID!
 }
 ```
@@ -236,11 +226,9 @@ input WorkbenchAssetRemoveInput {
 ### `WorkbenchAssetRemovePayload`
 
 ```graphql
-"""Payload returned by `workbenchAssetRemove`."""
+"""The result of `workbenchAssetRemove`."""
 type WorkbenchAssetRemovePayload {
-  """
-  The Asset id that was removed from the Workbench. Only the join is guaranteed removed; the Asset itself is also soft-deleted when the membership was `OWNED`.
-  """
+  """The ID of the removed asset."""
   removedAssetId: ID!
 }
 ```

package/docs/reference/management-api/schema/workflow-run.md

@@ -6,13 +6,14 @@ generated: true
 
 # Workflow run schema
 
-The operations and types that `workflow-run.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
 
 ### `workflowRun`
 
-Get a workflow run by ID. Requires scope: `ORGANIZATION_PROJECTS_READ`.
+Reads a workflow run.
+Scope: `ORGANIZATION_PROJECTS_READ`.
 
 ```graphql
 workflowRun(id: ID!): WorkflowRun @auth
@@ -23,13 +24,13 @@ workflowRun(id: ID!): WorkflowRun @auth
 ### `WorkflowRunStatus`
 
 ```graphql
-"""Where a run is in its life."""
+"""The state of a workflow run."""
 enum WorkflowRunStatus {
-  """The run has started and not yet ended."""
+  """Started and not yet ended."""
   RUNNING
-  """Every task the run reached succeeded."""
+  """Ended with every task succeeded."""
   COMPLETED
-  """A task failed and the run stopped there."""
+  """Stopped at a failed task."""
   FAILED
 }
 ```
@@ -37,7 +38,7 @@ enum WorkflowRunStatus {
 ### `WorkflowTaskType`
 
 ```graphql
-"""The kind of node a task ran."""
+"""The kind of node a workflow task ran."""
 enum WorkflowTaskType {
   """The trigger node the run started from."""
   ORIGIN
@@ -45,7 +46,7 @@ enum WorkflowTaskType {
   TOOL
   """A condition node, which chose a branch."""
   CONDITION
-  """A sleep node, which suspended the run."""
+  """A sleep node, which paused the run."""
   SLEEP
 }
 ```
@@ -53,13 +54,13 @@ enum WorkflowTaskType {
 ### `WorkflowTaskStatus`
 
 ```graphql
-"""Where a task is in its life."""
+"""The state of a workflow task."""
 enum WorkflowTaskStatus {
-  """The task has started and not yet ended."""
+  """Started and not yet ended."""
   RUNNING
-  """The task did its work."""
+  """Ended with its work done."""
   SUCCEEDED
-  """The task failed, and the run with it."""
+  """Failed, which stopped the run."""
   FAILED
 }
 ```
@@ -68,11 +69,11 @@ enum WorkflowTaskStatus {
 
 ```graphql
 """
-Sort keys accepted by `Workflow.runs(...)`. Pair with `reverse: true` to flip
-the order. A cursor belongs to the order it was issued under: change `sortKey` or `reverse` only from the first page.
+The orders `Workflow.runs` can sort by. A cursor is valid only for the `sortKey` and `reverse` it
+came from.
 """
 enum WorkflowRunSortKeys {
-  """Sort by `startedAt`."""
+  """By `startedAt`."""
   STARTED_AT
 }
 ```
@@ -81,13 +82,11 @@ enum WorkflowRunSortKeys {
 
 ```graphql
 """
-Sort keys accepted by `WorkflowRun.tasks(...)`. Pair with `reverse: true` to
-flip the order. A cursor belongs to the order it was issued under: change `sortKey` or `reverse` only from the first page.
+The orders `WorkflowRun.tasks` can sort by. A cursor is valid only for the `sortKey` and
+`reverse` it came from.
 """
 enum WorkflowTaskSortKeys {
-  """
-  Sort by `startedAt`: the order the run executed its tasks in, one at a time.
-  """
+  """By `startedAt`, which is the order the run ran its tasks in."""
   STARTED_AT
 }
 ```
@@ -96,55 +95,48 @@ enum WorkflowTaskSortKeys {
 
 ```graphql
 """
-One execution of a workflow: its published version, or its draft for a run
-started on the preview surface.
-
-A run is started by an event and walks the workflow's graph in order; `tasks`
-lists every node it reached. `failureReason` is set only when `status` is
-`FAILED` and names a node, a tool or an argument, never anything a tool read.
+One execution of a workflow, started by an event. A run executes the published workflow, or the
+draft for a run started in a preview.
 """
 type WorkflowRun {
-  """Unique run identifier."""
+  """The ID of the run."""
   id: ID!
-  """
-  ID of the workflow the run executed. Present after the workflow is deleted,
-  which is what a link to the run is built from.
-  """
+  """The ID of the workflow, which stays after the workflow is deleted."""
   workflowId: ID!
   """
-  ID of the workspace the workflow belongs to. A workflow ID is unique only within its workspace.
+  The ID of the workspace of the workflow. A workflow ID is unique only within its workspace.
   """
   workspaceId: ID!
   """
-  The workflow the run executed, or null once it is deleted. Requires scope:
-  `ORGANIZATION_WORKSPACE_READ`.
+  The workflow. Null when the workflow was deleted.
+  Scope: `ORGANIZATION_WORKSPACE_READ`.
   """
   workflow: Workflow
-  """Where the run is in its life."""
+  """The state of the run."""
   status: WorkflowRunStatus!
   """When the run started."""
   startedAt: DateTime!
-  """When the run ended, or null while it is running."""
+  """When the run ended. Null while it runs."""
   finishedAt: DateTime
-  """Why the run failed, or null unless it did."""
+  """
+  Why the run failed, naming a node, a tool or an argument but never data a tool read. Null unless
+  `status` is `FAILED`.
+  """
   failureReason: String
   """
-  True when a visitor on the preview surface started the run. A preview run
-  executes the workspace's draft workflow as it stood when the run started, and
-  its writes are real.
+  Whether a visitor started the run in a preview. A preview run executes the draft as it stood
+  when the run started, and its writes are real.
   """
   preview: Boolean!
   """
-  The tasks the run performed, one per visit of a node, in the order it reached them;
-  pass `reverse: true` for the latest first. Requires scope: `ORGANIZATION_PROJECTS_READ`.
+  The tasks of the run, one per visit of a node, in the order the run reached them.
+  Scope: `ORGANIZATION_PROJECTS_READ`.
   """
   tasks(first: Int, after: String, sortKey: WorkflowTaskSortKeys = STARTED_AT, reverse: Boolean = false): WorkflowTaskConnection! @auth
   """
-  The run's labels, ordered by namespace then key: state the run keeps about
-  itself, such as its outcome, or a person's notes on it. An expired label is
-  not listed. Run labels outlive every lead.
-  Write them with `labelsSet`, `ownerType: WORKFLOW_RUN` and the run's id.
-  Requires scope: `ORGANIZATION_PROJECTS_READ`.
+  The live labels on the run, ordered by namespace, then key. `labelsSet` with `ownerType:
+  WORKFLOW_RUN` writes them.
+  Scope: `ORGANIZATION_PROJECTS_READ`.
   """
   labels: [Label!]! @auth
 }
@@ -154,39 +146,36 @@ type WorkflowRun {
 
 ```graphql
 """
-One task of a workflow run: one visit of a node the run reached, and what came of it.
-
-A tool task's `operations` are the creates, updates and deletes it made to
-leads and labels. Other kinds perform none.
+One visit of a workflow run to a node, and its outcome. Only a tool task has `operations`.
 """
 type WorkflowTask {
-  """Unique task identifier. The same across every attempt of one visit."""
+  """The ID of the task, the same across every attempt of one visit."""
   id: ID!
   """
-  The ID of the graph node the task ran, as the workflow's `nodes` name it.
+  The ID of the node the task ran, as the `nodes` of the workflow name it.
   """
   stepId: ID!
   """
-  Which visit of its node the task is, from 1. A run that re-enters a node records each visit as a task of its own.
+  The number of the visit to the node, from 1. A run that enters a node again records a new task.
   """
   visit: Int!
   """The kind of node the task ran."""
   type: WorkflowTaskType!
-  """The tool a tool task ran, or null for another kind."""
+  """The tool the task ran. Null when the task is not a `TOOL` task."""
   tool: String
-  """Where the task is in its life."""
+  """The state of the task."""
   status: WorkflowTaskStatus!
   """When the task started."""
   startedAt: DateTime!
-  """When the task ended, or null while it is running."""
+  """When the task ended. Null while it runs."""
   finishedAt: DateTime
-  """Why the task failed, or null unless it did."""
+  """Why the task failed. Null unless `status` is `FAILED`."""
   failureReason: String
-  """The run this task belongs to."""
+  """The run of the task."""
   run: WorkflowRun!
   """
-  What the task did to leads and labels, latest first; pass `reverse: false`
-  for the order performed. Requires scope: `ORGANIZATION_PROJECTS_READ`.
+  The creates, updates and deletes the task made to leads and labels, newest first.
+  Scope: `ORGANIZATION_PROJECTS_READ`.
   """
   operations(first: Int, after: String, sortKey: OperationSortKeys = OCCURRED_AT, reverse: Boolean = true): OperationConnection! @auth
 }
@@ -195,15 +184,15 @@ type WorkflowTask {
 ### `WorkflowRunConnection`
 
 ```graphql
-"""Relay-style connection of workflow runs."""
+"""A page of workflow runs."""
 type WorkflowRunConnection {
-  """List of run edges."""
+  """The edges in this page."""
   edges: [WorkflowRunEdge!]!
-  """Flat list of runs, equivalent to `edges[].node`. Convenience accessor."""
+  """The runs in this page."""
   nodes: [WorkflowRun!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of runs in the list."""
+  """The total number of runs."""
   totalCount: Int!
 }
 ```
@@ -211,9 +200,9 @@ type WorkflowRunConnection {
 ### `WorkflowRunEdge`
 
 ```graphql
-"""Edge type for `WorkflowRunConnection`."""
+"""A workflow run in a page of results."""
 type WorkflowRunEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The run."""
   node: WorkflowRun!
@@ -223,17 +212,15 @@ type WorkflowRunEdge {
 ### `WorkflowTaskConnection`
 
 ```graphql
-"""Relay-style connection of workflow run tasks."""
+"""A page of workflow tasks."""
 type WorkflowTaskConnection {
-  """List of task edges."""
+  """The edges in this page."""
   edges: [WorkflowTaskEdge!]!
-  """
-  Flat list of tasks, equivalent to `edges[].node`. Convenience accessor.
-  """
+  """The tasks in this page."""
   nodes: [WorkflowTask!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of tasks the run performed."""
+  """The total number of tasks in the run."""
   totalCount: Int!
 }
 ```
@@ -241,9 +228,9 @@ type WorkflowTaskConnection {
 ### `WorkflowTaskEdge`
 
 ```graphql
-"""Edge type for `WorkflowTaskConnection`."""
+"""A workflow task in a page of results."""
 type WorkflowTaskEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The task."""
   node: WorkflowTask!
@@ -255,8 +242,8 @@ type WorkflowTaskEdge {
 ```graphql
 extend type Workflow {
   """
-  This workflow's runs in its workspace, oldest first; pass `reverse: true`
-  for the latest first. Requires scope: `ORGANIZATION_PROJECTS_READ`.
+  The runs of the workflow, oldest first.
+  Scope: `ORGANIZATION_PROJECTS_READ`.
   """
   runs(first: Int, after: String, last: Int, before: String, sortKey: WorkflowRunSortKeys = STARTED_AT, reverse: Boolean = false): WorkflowRunConnection! @auth
 }