picked 0.0.101 → 0.0.102-next.2

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

@@ -6,13 +6,14 @@ generated: true
 
 # Workflow schema
 
-The operations and types that `workflow.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
 
 ### `workflow`
 
-Get a workflow by ID.
+Reads a workflow.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 workflow(id: ID!): Workflow @auth
@@ -20,8 +21,7 @@ workflow(id: ID!): Workflow @auth
 
 ### `workflowTools`
 
-Every tool a workflow node may run, with the arguments each accepts. Read by
-the editor to build its node palette.
+Lists every tool a workflow node can run, with the arguments each takes.
 
 ```graphql
 workflowTools: [WorkflowToolDefinition!]! @auth
@@ -29,8 +29,8 @@ workflowTools: [WorkflowToolDefinition!]! @auth
 
 ### `workflows`
 
-List workflows in a workspace. Filter by name with `search` (case-insensitive
-substring) and order with `sortKey` (default `NAME`) plus `reverse`.
+Lists the workflows in a workspace. `search` matches a case-insensitive substring of the name.
+Scope: `ORGANIZATION_WORKSPACE_READ`.
 
 ```graphql
 workflows(first: Int, after: String, last: Int, before: String, workspaceId: ID!, search: String, sortKey: WorkflowSortKeys = NAME, reverse: Boolean = false): WorkflowConnection! @auth
@@ -40,7 +40,9 @@ workflows(first: Int, after: String, last: Int, before: String, workspaceId: ID!
 
 ### `workflowCreate`
 
-Create a new workflow. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Creates a workflow in a workspace. The caller must hold the scopes the tools of the graph need,
+as `Workflow.scopes` describes.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 workflowCreate(input: WorkflowCreateInput!): WorkflowCreatePayload! @auth
@@ -48,7 +50,8 @@ workflowCreate(input: WorkflowCreateInput!): WorkflowCreatePayload! @auth
 
 ### `workflowUpdate`
 
-Update a workflow. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Updates the name or the node visit limit of a workflow.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 workflowUpdate(input: WorkflowUpdateInput!): WorkflowUpdatePayload! @auth
@@ -56,8 +59,9 @@ workflowUpdate(input: WorkflowUpdateInput!): WorkflowUpdatePayload! @auth
 
 ### `workflowGraphUpdate`
 
-Apply a batch of changes to a workflow's graph, all or nothing. Requires
-scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Updates the graph of a workflow with a change set, all or nothing. A refused change set writes
+nothing and comes back in `errors`.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 workflowGraphUpdate(input: WorkflowGraphUpdateInput!): WorkflowGraphUpdatePayload! @auth
@@ -65,7 +69,9 @@ workflowGraphUpdate(input: WorkflowGraphUpdateInput!): WorkflowGraphUpdatePayloa
 
 ### `workflowDelete`
 
-Delete a workflow. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+Deletes a workflow. Published versions keep their copy, and an action that started it can start
+another workflow.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 workflowDelete(input: WorkflowDeleteInput!): WorkflowDeletePayload! @auth
@@ -73,10 +79,9 @@ workflowDelete(input: WorkflowDeleteInput!): WorkflowDeletePayload! @auth
 
 ### `workflowTestRun`
 
-Walk a workflow's draft graph once against a supplied trigger input, holding
-every write back, and return what each node did. Nothing is stored. Requires
-scope `ORGANIZATION_WORKSPACE_UPDATE` and every scope in `Workflow.scopes`;
-a refusal names each one missing.
+Tests a workflow by walking its draft graph once, holding back every write. Nothing is stored,
+and the caller must also hold every scope in `Workflow.scopes`.
+Scope: `ORGANIZATION_WORKSPACE_UPDATE`.
 
 ```graphql
 workflowTestRun(input: WorkflowTestRunInput!): WorkflowTestRunPayload! @auth
@@ -88,49 +93,43 @@ workflowTestRun(input: WorkflowTestRunInput!): WorkflowTestRunPayload! @auth
 
 ```graphql
 """
-An automation rule: when its trigger fires, its definition runs.
-
-The definition is a graph of `nodes` and `edges`, authored directly through
-`workflowCreate` and `workflowGraphUpdate`.
+An automation in a workspace: when its trigger fires, a run walks its graph of `nodes` and
+`edges`. Publishing freezes a copy into the version, so an edit does not change a published
+version.
 """
 type Workflow {
-  """Unique workflow identifier."""
+  """The ID of the workflow."""
   id: ID!
-  """Display name of the workflow."""
+  """The name of the workflow."""
   name: String!
-  """
-  What causes this workflow to run. Chosen at create and fixed for the workflow's life.
-  """
+  """What starts a run. Set at creation and fixed after."""
   trigger: WorkflowTrigger!
   """
-  Scopes a run of this workflow acts with, derived from the tools its graph
-  names and rewritten whenever the graph is written. An author may only save a
-  graph naming tools they hold these for.
+  The scopes a run acts with, set by the tools the graph names each time the graph is saved.
+  Saving needs each of them except `ORGANIZATION_LEADS_CREATE`, `ORGANIZATION_ACTION_RUNS_READ`,
+  `ORGANIZATION_ACTION_RUNS_UPDATE` and `ORGANIZATION_EXTERNAL_APIS_CALL`, which any author grants.
   """
   scopes: [Scope!]!
-  """Nodes in the workflow graph, typed by their `__typename`."""
+  """The nodes of the graph."""
   nodes: [WorkflowNode!]!
-  """Edges connecting nodes in the workflow graph."""
+  """The edges of the graph."""
   edges: [WorkflowEdge!]!
   """
-  How many times a run may visit any one node, from 1 to 100; 10 unless set. A run that
-  arrives at a node it has already visited this many times fails with `loop_limit_reached`.
+  The most times a run can visit one node, from 1 to 100; 10 by default. A run that reaches a node
+  this many times fails with `loop_limit_reached`.
   """
   maxNodeVisits: Int!
-  """When this workflow was created."""
+  """When the workflow was created."""
   createdAt: DateTime!
-  """When this workflow was last updated."""
+  """When the workflow last changed."""
   updatedAt: DateTime!
-  """The workspace this workflow belongs to."""
+  """The workspace of the workflow."""
   workspace: Workspace!
-  """
-  The workspace ID this workflow belongs to (denormalised for query convenience).
-  """
+  """The ID of the workspace of the workflow."""
   workspaceId: ID
   """
-  Every path this workflow's templates and rules may address: `trigger`, `nodes.<id>` by
-  the tool the node runs, and the run's variables beneath `run`, `workflow` and `current`.
-  Read by the editor's reference picker and its condition builder.
+  Every path the templates and rules of the workflow can address: the trigger, the output of each
+  tool by `nodes.<id>`, and the run variables.
   """
   references: WorkflowReferences!
 }
@@ -139,13 +138,11 @@ type Workflow {
 ### `WorkflowTriggerType`
 
 ```graphql
-"""
-Which kind of trigger this is: what tells `WorkflowEventTrigger` and `WorkflowActionTrigger` apart.
-"""
+"""The kind of workflow trigger."""
 enum WorkflowTriggerType {
   """A domain event starts the run."""
   EVENT
-  """One action starts the run."""
+  """An action starts the run."""
   ACTION
 }
 ```
@@ -154,10 +151,8 @@ enum WorkflowTriggerType {
 
 ```graphql
 """
-Domain events a workflow can be bound to.
-
-An action is reached through an `ACTION` trigger rather than an event, so that a
-workflow names the one action it answers to.
+The domain events that can start a workflow. An action starts a workflow through an `ACTION`
+trigger.
 """
 enum WorkflowEventName {
   """A workspace was created."""
@@ -168,11 +163,11 @@ enum WorkflowEventName {
   WORKSPACE_DELETED
   """A workspace version was published."""
   WORKSPACE_PUBLISHED
-  """A feature was created."""
+  """A feature flag was created."""
   FEATURE_CREATED
-  """A feature was updated."""
+  """A feature flag was updated."""
   FEATURE_UPDATED
-  """A feature was deleted."""
+  """A feature flag was deleted."""
   FEATURE_DELETED
   """A step was deleted."""
   STEP_DELETED
@@ -186,11 +181,9 @@ enum WorkflowEventName {
 ### `WorkflowTrigger`
 
 ```graphql
-"""
-What starts a workflow's run. Use `__typename` to discriminate the implementation.
-"""
+"""What starts the runs of a workflow. `__typename` names the kind."""
 interface WorkflowTrigger {
-  """Which kind this is. `__typename` says the same thing."""
+  """The kind of trigger."""
   type: WorkflowTriggerType!
 }
 ```
@@ -198,8 +191,9 @@ interface WorkflowTrigger {
 ### `WorkflowEventTrigger`
 
 ```graphql
-"""A workflow started by a domain event."""
+"""A trigger that starts a run on a domain event."""
 type WorkflowEventTrigger implements WorkflowTrigger {
+  """The kind of trigger."""
   type: WorkflowTriggerType!
   """The event that starts the run."""
   eventName: WorkflowEventName!
@@ -210,15 +204,14 @@ type WorkflowEventTrigger implements WorkflowTrigger {
 
 ```graphql
 """
-A workflow started by one action. An action starts at most one workflow.
+A trigger that starts a run when an action runs. An action starts at most one workflow.
 """
 type WorkflowActionTrigger implements WorkflowTrigger {
+  """The kind of trigger."""
   type: WorkflowTriggerType!
-  """ID of the action whose run starts the workflow."""
+  """The ID of the action."""
   actionId: ID!
-  """
-  The action whose run starts the workflow. Null once that action is deleted.
-  """
+  """The action. Null when the action was deleted."""
   action: Action
 }
 ```
@@ -226,16 +219,14 @@ type WorkflowActionTrigger implements WorkflowTrigger {
 ### `WorkflowTriggerInput`
 
 ```graphql
-"""
-Input form of a workflow's trigger. Only the field matching `type` is read.
-"""
+"""A workflow trigger to set. Only the field that matches `type` is read."""
 input WorkflowTriggerInput {
-  """Which kind of trigger this is."""
+  """The kind of trigger."""
   type: WorkflowTriggerType!
-  """For EVENT triggers: the domain event that starts the run."""
+  """The event that starts the run, for an `EVENT` trigger."""
   eventName: WorkflowEventName
   """
-  For ACTION triggers: the action to bind, which must start no workflow yet.
+  The ID of an action that starts no workflow yet, for an `ACTION` trigger.
   """
   actionId: ID
 }
@@ -244,15 +235,15 @@ input WorkflowTriggerInput {
 ### `WorkflowNodeType`
 
 ```graphql
-"""Which kind of node this is: what tells the four node types apart."""
+"""The kind of workflow node."""
 enum WorkflowNodeType {
   """Where a run starts. Exactly one per workflow."""
   ORIGIN
-  """A node that runs a registered tool."""
+  """Runs a tool."""
   TOOL
-  """A node that branches the run on a rule."""
+  """Chooses a branch by a rule."""
   CONDITION
-  """A node that suspends the run for a duration."""
+  """Pauses the run for a duration."""
   SLEEP
 }
 ```
@@ -260,16 +251,13 @@ enum WorkflowNodeType {
 ### `WorkflowEdgeHandle`
 
 ```graphql
-"""
-Edge handle for `WorkflowConditionNode` outgoing edges. Picks which branch the
-run follows when the condition resolves true / false.
-"""
+"""The exit an edge leaves a node by."""
 enum WorkflowEdgeHandle {
-  """The TRUE branch of a condition."""
+  """The branch a condition takes when its rule is true."""
   TRUE
-  """The FALSE branch of a condition."""
+  """The branch a condition takes when its rule is false."""
   FALSE
-  """A tool's error exit, which a run follows when the tool fails."""
+  """The exit a run takes when a tool fails."""
   ERROR
 }
 ```
@@ -277,17 +265,13 @@ enum WorkflowEdgeHandle {
 ### `WorkflowNode`
 
 ```graphql
-"""
-A node in the workflow graph. Use `__typename` to discriminate the implementation.
-"""
+"""A node in the graph of a workflow. `__typename` names the kind."""
 interface WorkflowNode {
-  """
-  Stable node identifier within the graph, and the run's durable step id.
-  """
+  """The ID of the node, unique in the graph."""
   id: ID!
-  """Which kind of node this is. `__typename` says the same thing."""
+  """The kind of node."""
   type: WorkflowNodeType!
-  """Canvas position for the dashboard editor."""
+  """The position of the node on the canvas."""
   position: Position!
 }
 ```
@@ -295,14 +279,13 @@ interface WorkflowNode {
 ### `WorkflowOriginNode`
 
 ```graphql
-"""
-Where a run starts. Exactly one per workflow.
-
-It carries no trigger: what starts a workflow is the workflow's own `trigger`.
-"""
+"""The node where every run starts. Exactly one per workflow."""
 type WorkflowOriginNode implements WorkflowNode {
+  """The ID of the node, unique in the graph."""
   id: ID!
+  """The kind of node."""
   type: WorkflowNodeType!
+  """The position of the node on the canvas."""
   position: Position!
 }
 ```
@@ -310,14 +293,17 @@ type WorkflowOriginNode implements WorkflowNode {
 ### `WorkflowToolNode`
 
 ```graphql
-"""A node that runs a registered tool with the given configuration."""
+"""A node that runs a tool."""
 type WorkflowToolNode implements WorkflowNode {
+  """The ID of the node, unique in the graph."""
   id: ID!
+  """The kind of node."""
   type: WorkflowNodeType!
+  """The position of the node on the canvas."""
   position: Position!
-  """Name of the tool this node runs."""
+  """The name of the tool."""
   tool: String!
-  """Values for the arguments that tool declares."""
+  """The values of the arguments of the tool."""
   configuration: JSON!
 }
 ```
@@ -326,13 +312,16 @@ type WorkflowToolNode implements WorkflowNode {
 
 ```graphql
 """
-A node that branches the run. Outgoing edges carry `sourceHandle: TRUE | FALSE`.
+A node that chooses a branch. Its outgoing edges carry `sourceHandle` `TRUE` or `FALSE`.
 """
 type WorkflowConditionNode implements WorkflowNode {
+  """The ID of the node, unique in the graph."""
   id: ID!
+  """The kind of node."""
   type: WorkflowNodeType!
+  """The position of the node on the canvas."""
   position: Position!
-  """The rule evaluated when the run reaches this node."""
+  """The rule the node evaluates."""
   logic: JSON!
 }
 ```
@@ -340,13 +329,16 @@ type WorkflowConditionNode implements WorkflowNode {
 ### `WorkflowSleepNode`
 
 ```graphql
-"""A node that suspends the run."""
+"""A node that pauses the run."""
 type WorkflowSleepNode implements WorkflowNode {
+  """The ID of the node, unique in the graph."""
   id: ID!
+  """The kind of node."""
   type: WorkflowNodeType!
+  """The position of the node on the canvas."""
   position: Position!
   """
-  How long the run suspends for, as a count and a unit: `500ms`, `30s`, `5m`, `2h`, `1d`. At most one day.
+  The length of the pause, as a count and a unit such as `500ms`, `30s`, `5m`, `2h` or `1d`. At most one day.
   """
   duration: String!
 }
@@ -355,16 +347,16 @@ type WorkflowSleepNode implements WorkflowNode {
 ### `WorkflowEdge`
 
 ```graphql
-"""An edge connecting two nodes in the workflow graph."""
+"""A connection between two nodes in the graph of a workflow."""
 type WorkflowEdge {
-  """Stable edge identifier within the graph."""
+  """The ID of the edge, unique in the graph."""
   id: ID!
-  """Node the edge leaves."""
+  """The ID of the node the edge leaves."""
   sourceNodeId: ID!
-  """Node the edge arrives at."""
+  """The ID of the node the edge arrives at."""
   destinationNodeId: ID!
   """
-  The exit the edge leaves by: a `WorkflowConditionNode` branch (TRUE / FALSE), or a `WorkflowToolNode`'s error exit (ERROR).
+  The exit the edge leaves by: `TRUE` or `FALSE` from a condition, `ERROR` from a tool. Null for any other exit.
   """
   sourceHandle: WorkflowEdgeHandle
 }
@@ -373,17 +365,12 @@ type WorkflowEdge {
 ### `WorkflowToolNodeInput`
 
 ```graphql
-"""
-The data a `TOOL` node carries: which registered tool runs, and with what.
-
-A tool's arguments belong to one node in one workflow, so they sit on the node
-rather than on an entity of their own.
-"""
+"""The data of a `TOOL` node: the tool and its arguments."""
 input WorkflowToolNodeInput {
-  """Name of a registered tool, as `workflowTools` lists it."""
+  """The name of a tool that `workflowTools` lists."""
   name: String!
   """
-  Values for the arguments that tool declares. Omit for a tool that takes none.
+  The values of the arguments of the tool. Omit for a tool with no arguments.
   """
   configuration: JSON
 }
@@ -392,11 +379,9 @@ input WorkflowToolNodeInput {
 ### `WorkflowConditionNodeInput`
 
 ```graphql
-"""The data a `CONDITION` node carries: the rule that picks the branch."""
+"""The data of a `CONDITION` node: the rule that chooses the branch."""
 input WorkflowConditionNodeInput {
-  """
-  The rule evaluated when the run reaches the node. Outgoing edges carry `sourceHandle`.
-  """
+  """The rule the node evaluates."""
   logic: JSON!
 }
 ```
@@ -404,9 +389,11 @@ input WorkflowConditionNodeInput {
 ### `WorkflowSleepNodeInput`
 
 ```graphql
-"""The data a `SLEEP` node carries: how long the run suspends."""
+"""The data of a `SLEEP` node: the length of the pause."""
 input WorkflowSleepNodeInput {
-  """A count and a unit: `500ms`, `30s`, `5m`, `2h`, `1d`. At most one day."""
+  """
+  A count and a unit, such as `500ms`, `30s`, `5m`, `2h` or `1d`. At most one day.
+  """
   duration: String!
 }
 ```
@@ -415,21 +402,20 @@ input WorkflowSleepNodeInput {
 
 ```graphql
 """
-Input form of a node in the workflow graph. Every node carries an id, a kind and
-a position; the block matching its kind carries the rest. `ORIGIN` has no block.
+A node to set in a graph. The block that matches `type` carries its data; `ORIGIN` has none.
 """
 input WorkflowNodeInput {
-  """Graph-unique identifier, and the run's durable step id."""
+  """The ID of the node, unique in the graph."""
   id: ID!
-  """Which kind of node to create."""
+  """The kind of node."""
   type: WorkflowNodeType!
-  """Canvas position."""
+  """The position of the node on the canvas."""
   position: PositionInput!
-  """For TOOL nodes: the tool to run and its arguments."""
+  """The tool and its arguments, for a `TOOL` node."""
   tool: WorkflowToolNodeInput
-  """For CONDITION nodes: the rule that picks the branch."""
+  """The rule, for a `CONDITION` node."""
   condition: WorkflowConditionNodeInput
-  """For SLEEP nodes: how long the run suspends."""
+  """The length of the pause, for a `SLEEP` node."""
   sleep: WorkflowSleepNodeInput
 }
 ```
@@ -437,16 +423,16 @@ input WorkflowNodeInput {
 ### `WorkflowEdgeInput`
 
 ```graphql
-"""Input form of an edge in the workflow graph."""
+"""An edge to set in a graph."""
 input WorkflowEdgeInput {
-  """Graph-unique identifier."""
+  """The ID of the edge, unique in the graph."""
   id: ID!
-  """Node the edge leaves."""
+  """The ID of the node the edge leaves."""
   sourceNodeId: ID!
-  """Node the edge arrives at."""
+  """The ID of the node the edge arrives at."""
   destinationNodeId: ID!
   """
-  The exit the edge leaves by: a `WorkflowConditionNode` branch (TRUE / FALSE), or a `WorkflowToolNode`'s error exit (ERROR).
+  The exit the edge leaves by: `TRUE` or `FALSE` from a condition, `ERROR` from a tool.
   """
   sourceHandle: WorkflowEdgeHandle
 }
@@ -456,29 +442,27 @@ input WorkflowEdgeInput {
 
 ```graphql
 """
-The type an argument takes.
-
-Every argument also accepts a Liquid template — `{{ nodes.n1.leads[0].id }}` — in place of a
-literal. A template that is the whole value keeps the type of what it names; one mixed with
-text renders to text and is read as the declared type when the node runs.
+The type of a tool argument. Every argument also takes a workflow template such as
+`{{ nodes.n1.leads[0].id }}`: a template that is the whole value keeps the type of what it names,
+and one mixed with text is read as the declared type when the node runs.
 """
 enum WorkflowArgumentType {
-  """A text value."""
+  """Text."""
   STRING
-  """A numeric value."""
+  """A number."""
   NUMBER
-  """A true / false value."""
+  """True or false."""
   BOOLEAN
   """Any JSON value."""
   JSON
   """
-  A query over one resource, written as a string in that resource's own query language.
-  A template may stand in a clause's value and nowhere else.
+  A query in the query language of one resource. A template can stand only in the value of a
+  clause.
   """
   QUERY
   """
-  One record of the resource type `resourceType` names, written as a reference to it.
-  The value resolves to that record's identifier before the tool runs.
+  A reference to one record of the type `resourceType` names, which resolves to the ID of the
+  record before the tool runs.
   """
   REFERENCE
 }
@@ -487,36 +471,31 @@ enum WorkflowArgumentType {
 ### `WorkflowToolArgument`
 
 ```graphql
-"""One argument a tool accepts."""
+"""An argument a tool takes."""
 type WorkflowToolArgument {
-  """Argument name, as it appears in a tool node's `configuration`."""
-  name: String!
   """
-  The argument's name for authors, such as `Lead`, which an editor's form field takes.
+  The name of the argument, as a key in the `configuration` of a tool node.
   """
+  name: String!
+  """The display name of the argument, such as `Lead`."""
   label: String!
-  """The type the argument takes."""
+  """The type of the argument."""
   type: WorkflowArgumentType!
   """
-  For a `JSON` argument, the structured shape its value takes, such as `labels` — the
-  editor renders the control that shape calls for and validates against it. Null for
-  free-form JSON. Unlike `type` this vocabulary is open: an editor that does not know the
-  shape edits the value as raw JSON.
+  The structured shape of a `JSON` argument, such as `labels`. Null for free-form JSON. The set of
+  shapes can grow; edit an unknown shape as raw JSON.
   """
   shape: String
   """
-  For a `REFERENCE` argument, the resource type the value must name, such as `Lead` — the
-  editor offers only the paths that produce one. Null otherwise. Like `shape` this
-  vocabulary is open, and it is matched against `WorkflowReferenceEntry.resourceType` by
-  equality.
+  The resource type a `REFERENCE` argument names, such as `Lead`, matched by equality against
+  `WorkflowReferenceEntry.resourceType`. Null for other types.
   """
   resourceType: String
   """
-  For a `STRING` argument, the literals it admits, so the editor offers a choice rather
-  than free text. Null when the argument takes any string.
+  The values a `STRING` argument accepts. Null when it accepts any string.
   """
   options: [String!]
-  """Whether the argument must be given."""
+  """Whether the argument is required."""
   required: Boolean!
   """What the argument is for."""
   description: String!
@@ -526,19 +505,18 @@ type WorkflowToolArgument {
 ### `WorkflowToolDefinition`
 
 ```graphql
-"""A tool a workflow node may run."""
+"""A tool a workflow node can run."""
 type WorkflowToolDefinition {
-  """Name a node references."""
+  """The name a tool node uses."""
   name: String!
-  """The tool's name for authors, such as `External endpoint`."""
+  """The display name of the tool, such as `External endpoint`."""
   label: String!
   """What the tool does."""
   description: String!
-  """The arguments it accepts."""
+  """The arguments the tool takes."""
   arguments: [WorkflowToolArgument!]!
   """
-  The scopes a run must hold for this tool to run. Empty for a tool that touches
-  no data. Read by the editor to show which tools the viewer can place.
+  The scopes a run needs to run the tool. Empty for a tool that touches no data.
   """
   scopes: [Scope!]!
 }
@@ -547,20 +525,20 @@ type WorkflowToolDefinition {
 ### `WorkflowReferenceType`
 
 ```graphql
-"""How a reference entry's value reads."""
+"""The type of the value at a reference path."""
 enum WorkflowReferenceType {
-  """A text value."""
+  """Text."""
   STRING
-  """A numeric value."""
+  """A number."""
   NUMBER
-  """A true / false value."""
+  """True or false."""
   BOOLEAN
-  """Any JSON value; paths beneath it are not listed."""
+  """Any JSON value. Paths beneath it are not listed."""
   JSON
-  """A record whose fields are listed beneath it."""
+  """A record, with its fields listed beneath it."""
   OBJECT
   """
-  A list of records, addressed by index; `.0.` entries describe each item and `.truncated` says whether the list was cut at its bound.
+  A list addressed by index. `.0.` entries describe each item, and `.truncated` says whether the list was cut short.
   """
   COLLECTION
 }
@@ -570,28 +548,24 @@ enum WorkflowReferenceType {
 
 ```graphql
 """
-One path a workflow's templates and rules may address, with what the picker shows for it.
-
-The path is relative to its owner and written in the dotted form a rule reads —
-`action.responses.email` beneath `trigger`, `leads.0.id` beneath `nodes.<id>`, and
-`current.startedAt` from the root for a variable. A template writes an index as
-`leads[0].id`.
+A path that the templates and rules of a workflow can address. The path is relative to its owner,
+in dotted form: `action.responses.email` beneath `trigger`, `leads.0.id` beneath `nodes.<id>`. A
+template writes an index as `leads[0].id`.
 """
 type WorkflowReferenceEntry {
   """The path, relative to its owner."""
   path: String!
-  """How the value reads."""
+  """The type of the value."""
   type: WorkflowReferenceType!
-  """A human-readable label."""
+  """The display name of the path."""
   label: String!
-  """A few words on what the path holds, shown beneath the label."""
+  """What the path holds."""
   description: String!
-  """A representative value, declared with the tool."""
+  """An example value."""
   example: JSON!
   """
-  The resource type this path materialises to, such as `Lead`, for a path that names a
-  whole record or that record's identifier. Null for everything else. Matched against
-  `WorkflowToolArgument.resourceType` by equality.
+  The resource type of a path that names a whole record or its ID, such as `Lead`, matched by
+  equality against `WorkflowToolArgument.resourceType`. Null for other paths.
   """
   resourceType: String
 }
@@ -601,12 +575,12 @@ type WorkflowReferenceEntry {
 
 ```graphql
 """
-The paths one tool's output makes addressable beneath `nodes.<id>` for every node running it.
+The paths the output of one tool adds beneath `nodes.<id>` for each node that runs it.
 """
 type WorkflowToolReferences {
-  """The tool name, as a node's `tool` names it."""
+  """The name of the tool."""
   tool: String!
-  """The addressable paths, relative to the node."""
+  """The paths, relative to the node."""
   entries: [WorkflowReferenceEntry!]!
 }
 ```
@@ -615,24 +589,21 @@ type WorkflowToolReferences {
 
 ```graphql
 """
-Everything one workflow's templates and rules may address: the trigger, resolved from the
-workflow's trigger, each tool's output with its shapes resolved against the workspace's
-fields, and the run's variables. The editor filters the tool outputs to the nodes upstream of
-the one being edited.
+Every path the templates and rules of one workflow can address: the trigger, the output of each
+tool with its shapes resolved against the fields of the workspace, and the run variables.
 """
 type WorkflowReferences {
   """
-  Paths beneath `trigger`: `action` and its responses on an action-triggered workflow, `event` on an event-triggered one.
+  The paths beneath `trigger`: `action` and its responses for an `ACTION` trigger, `event` for an `EVENT` trigger.
   """
   trigger: [WorkflowReferenceEntry!]!
-  """Paths beneath `nodes.<id>`, by the tool the node runs."""
+  """The paths beneath `nodes.<id>`, by the tool the node runs."""
   tools: [WorkflowToolReferences!]!
   """
-  The run's variables, the same on every workflow, each path written from its root:
-  `run.id`, `run.startedAt` and `run.preview` for the run; `workflow.id` and
-  `workflow.name` for the workflow; `current.id`, `current.startedAt` and `current.visit`
-  for the node that reads them. Times are ISO 8601 in UTC. A save refuses any other path
-  beneath these three roots.
+  The run variables, the same on every workflow, each written from its root: `run.id`,
+  `run.startedAt`, `run.preview`, `workflow.id`, `workflow.name`, `current.id`,
+  `current.startedAt` and `current.visit`. Times are in UTC. A save refuses any other path beneath
+  these three roots.
   """
   variables: [WorkflowReferenceEntry!]!
 }
@@ -641,11 +612,11 @@ type WorkflowReferences {
 ### `WorkflowChangesInput`
 
 ```graphql
-"""Container for all change operations on a workflow graph."""
+"""The changes to a workflow graph."""
 input WorkflowChangesInput {
-  """Node changes in the workflow graph."""
+  """The changes to nodes."""
   nodes: WorkflowNodeChangesInput
-  """Edge changes connecting nodes."""
+  """The changes to edges."""
   edges: WorkflowEdgeChangesInput
 }
 ```
@@ -653,17 +624,17 @@ input WorkflowChangesInput {
 ### `WorkflowNodeChangesInput`
 
 ```graphql
-"""Node-level changes within a `workflowGraphUpdate` batch."""
+"""The changes to the nodes of a workflow graph."""
 input WorkflowNodeChangesInput {
-  """
-  Nodes to create, each named by its `clientId` until the server mints its id.
-  """
+  """The nodes to create, each named by its `clientId`."""
   create: [WorkflowNodeCreateData!]
   """
-  Fields to merge into the nodes they name. An id the graph lacks is ignored.
+  The changes to existing nodes. An ID the graph does not have is ignored.
   """
   update: [WorkflowNodeUpdateData!]
-  """Node ids to delete. Edges touching a deleted node are dropped with it."""
+  """
+  The IDs of the nodes to delete. The edges of a deleted node are deleted with it.
+  """
   delete: [ID!]
 }
 ```
@@ -671,24 +642,22 @@ input WorkflowNodeChangesInput {
 ### `WorkflowNodeCreateData`
 
 ```graphql
-"""
-A node to add to the graph. The block matching `type` carries its data.
-"""
+"""A node to create. The block that matches `type` carries its data."""
 input WorkflowNodeCreateData {
   """
-  Client-generated id, for cross-referencing from edges in the same change set.
-  The server mints the persisted id and returns the pair in `idMappings`.
+  An ID of your choice, which edges in the same change set can name. The result maps it to the
+  node ID in `idMappings`.
   """
   clientId: ID!
-  """Which kind of node to create."""
+  """The kind of node."""
   type: WorkflowNodeType!
-  """Canvas position."""
+  """The position of the node on the canvas."""
   position: PositionInput!
-  """For TOOL nodes: the tool to run and its arguments."""
+  """The tool and its arguments, for a `TOOL` node."""
   tool: WorkflowToolNodeInput
-  """For CONDITION nodes: the rule that picks the branch."""
+  """The rule, for a `CONDITION` node."""
   condition: WorkflowConditionNodeInput
-  """For SLEEP nodes: how long the run suspends."""
+  """The length of the pause, for a `SLEEP` node."""
   sleep: WorkflowSleepNodeInput
 }
 ```
@@ -697,19 +666,19 @@ input WorkflowNodeCreateData {
 
 ```graphql
 """
-Fields to merge into an existing node. Omit a field to leave it unchanged; a
-kind block that is given replaces that kind's data whole.
+A change to an existing node. Omit a field to keep its value; a kind block replaces all the data
+of that kind.
 """
 input WorkflowNodeUpdateData {
-  """Id of the node to change."""
+  """The ID of the node."""
   id: ID!
-  """New canvas position."""
+  """The position of the node on the canvas."""
   position: PositionInput
-  """For TOOL nodes: the tool to run and its arguments."""
+  """The tool and its arguments, for a `TOOL` node."""
   tool: WorkflowToolNodeInput
-  """For CONDITION nodes: the rule that picks the branch."""
+  """The rule, for a `CONDITION` node."""
   condition: WorkflowConditionNodeInput
-  """For SLEEP nodes: how long the run suspends."""
+  """The length of the pause, for a `SLEEP` node."""
   sleep: WorkflowSleepNodeInput
 }
 ```
@@ -717,17 +686,15 @@ input WorkflowNodeUpdateData {
 ### `WorkflowEdgeChangesInput`
 
 ```graphql
-"""Edge-level changes within a `workflowGraphUpdate` batch."""
+"""The changes to the edges of a workflow graph."""
 input WorkflowEdgeChangesInput {
-  """
-  Edges to create, each named by its `clientId` until the server mints its id.
-  """
+  """The edges to create, each named by its `clientId`."""
   create: [WorkflowEdgeCreateInput!]
   """
-  Fields to merge into the edges they name. An id the graph lacks is ignored.
+  The changes to existing edges. An ID the graph does not have is ignored.
   """
   update: [WorkflowEdgeUpdateInput!]
-  """Edge ids to delete."""
+  """The IDs of the edges to delete."""
   delete: [ID!]
 }
 ```
@@ -736,31 +703,32 @@ input WorkflowEdgeChangesInput {
 
 ```graphql
 """
-An edge to add to the graph. Each endpoint is named one way: by its persisted id, or by the client id of a node created in the same change set.
+An edge to create. Name each end once: by node ID, or by the `clientId` of a node created in the
+same change set.
 """
 input WorkflowEdgeCreateInput {
   """
-  Client-generated id. The server mints the persisted id and returns the pair in `idMappings`.
+  An ID of your choice. The result maps it to the edge ID in `idMappings`.
   """
   clientId: ID!
   """
-  Node the edge leaves, by persisted id. Mutually exclusive with `sourceNodeClientId`.
+  The ID of the node the edge leaves. Not allowed with `sourceNodeClientId`.
   """
   sourceNodeId: ID
   """
-  Node the edge leaves, created in this same change set. Mutually exclusive with `sourceNodeId`.
+  The `clientId` of a new node the edge leaves. Not allowed with `sourceNodeId`.
   """
   sourceNodeClientId: ID
   """
-  Node the edge arrives at, by persisted id. Mutually exclusive with `destinationNodeClientId`.
+  The ID of the node the edge arrives at. Not allowed with `destinationNodeClientId`.
   """
   destinationNodeId: ID
   """
-  Node the edge arrives at, created in this same change set. Mutually exclusive with `destinationNodeId`.
+  The `clientId` of a new node the edge arrives at. Not allowed with `destinationNodeId`.
   """
   destinationNodeClientId: ID
   """
-  The exit the edge leaves by: a `WorkflowConditionNode` branch (TRUE / FALSE), or a `WorkflowToolNode`'s error exit (ERROR).
+  The exit the edge leaves by: `TRUE` or `FALSE` from a condition, `ERROR` from a tool.
   """
   sourceHandle: WorkflowEdgeHandle
 }
@@ -769,17 +737,17 @@ input WorkflowEdgeCreateInput {
 ### `WorkflowEdgeUpdateInput`
 
 ```graphql
-"""
-Fields to merge into an existing edge. Omit a field to leave it unchanged.
-"""
+"""A change to an existing edge. Omit a field to keep its value."""
 input WorkflowEdgeUpdateInput {
-  """Id of the edge to change."""
+  """The ID of the edge."""
   id: ID!
-  """New source node id."""
+  """The ID of the node the edge leaves."""
   sourceNodeId: ID
-  """New destination node id."""
+  """The ID of the node the edge arrives at."""
   destinationNodeId: ID
-  """New exit: TRUE or FALSE off a condition, ERROR off a tool."""
+  """
+  The exit the edge leaves by: `TRUE` or `FALSE` from a condition, `ERROR` from a tool.
+  """
   sourceHandle: WorkflowEdgeHandle
 }
 ```
@@ -787,19 +755,15 @@ input WorkflowEdgeUpdateInput {
 ### `WorkflowConnection`
 
 ```graphql
-"""
-Relay-style connection of workflows, with both an `edges` list and a flat `nodes` accessor.
-"""
+"""A page of workflows."""
 type WorkflowConnection {
-  """List of workflow edges."""
+  """The edges in this page."""
   edges: [WorkflowConnectionEdge!]!
-  """
-  Flat list of workflows, equivalent to `edges[].node`. Convenience accessor.
-  """
+  """The workflows in this page."""
   nodes: [Workflow!]!
-  """Pagination metadata."""
+  """Where this page sits in the list."""
   pageInfo: PageInfo!
-  """Total number of workflows."""
+  """The total number of workflows."""
   totalCount: Int!
 }
 ```
@@ -807,9 +771,9 @@ type WorkflowConnection {
 ### `WorkflowConnectionEdge`
 
 ```graphql
-"""Edge type for `WorkflowConnection`."""
+"""A workflow in a page of results."""
 type WorkflowConnectionEdge {
-  """Pagination cursor for this edge."""
+  """The cursor of this edge."""
   cursor: String!
   """The workflow."""
   node: Workflow!
@@ -819,19 +783,19 @@ type WorkflowConnectionEdge {
 ### `WorkflowCreateInput`
 
 ```graphql
-"""Input for `workflowCreate`."""
+"""The input of `workflowCreate`."""
 input WorkflowCreateInput {
-  """Workspace ID to create the workflow in."""
+  """The ID of the workspace."""
   workspaceId: ID!
   """
-  Display name. Omit it to derive one from the trigger, suffixed until unused.
+  The name. When omitted, a name taken from the trigger, with a number added until it is unique.
   """
   name: String
-  """What causes this workflow to run."""
+  """What starts a run. Fixed after creation."""
   trigger: WorkflowTriggerInput!
-  """Nodes of the graph to build. The `ORIGIN` node is added automatically."""
+  """The nodes of the graph. The `ORIGIN` node is added when absent."""
   nodes: [WorkflowNodeInput!]
-  """Edges of the graph to build. Read only when `nodes` is given."""
+  """The edges of the graph. Ignored without `nodes`."""
   edges: [WorkflowEdgeInput!]
 }
 ```
@@ -839,9 +803,9 @@ input WorkflowCreateInput {
 ### `WorkflowCreatePayload`
 
 ```graphql
-"""Payload returned by `workflowCreate`."""
+"""The result of `workflowCreate`."""
 type WorkflowCreatePayload {
-  """The created workflow."""
+  """The workflow."""
   workflow: Workflow
 }
 ```
@@ -849,17 +813,13 @@ type WorkflowCreatePayload {
 ### `WorkflowUpdateInput`
 
 ```graphql
-"""
-Input for `workflowUpdate`. Omit a field to leave it unchanged. The trigger is fixed at create.
-"""
+"""The input of `workflowUpdate`. Omit a field to keep its value."""
 input WorkflowUpdateInput {
-  """Workflow ID."""
+  """The ID of the workflow."""
   id: ID!
-  """New display name."""
+  """The name."""
   name: String
-  """
-  How many times a run may visit any one node, from 1 to 100. A value outside that range is refused.
-  """
+  """The most times a run can visit one node, from 1 to 100."""
   maxNodeVisits: Int
 }
 ```
@@ -868,23 +828,16 @@ input WorkflowUpdateInput {
 
 ```graphql
 """
-Input for `workflowGraphUpdate`.
-
-The whole change set is applied or none of it is: the graph is validated once,
-after every change lands, so a set that would leave it unrunnable is refused
-entire and nothing is written.
+The input of `workflowGraphUpdate`. Omit a field to keep its value. `changes` is required.
 """
 input WorkflowGraphUpdateInput {
-  """The workflow to update."""
+  """The ID of the workflow."""
   workflowId: ID!
-  """New display name."""
+  """The name."""
   name: String
-  """
-  How many times a run may visit any one node, from 1 to 100, set with the change set.
-  A value outside that range comes back in `errors` and nothing is written.
-  """
+  """The most times a run can visit one node, from 1 to 100."""
   maxNodeVisits: Int
-  """All changes to apply to the workflow graph."""
+  """The changes to the graph."""
   changes: WorkflowChangesInput!
 }
 ```
@@ -892,24 +845,24 @@ input WorkflowGraphUpdateInput {
 ### `WorkflowGraphUpdatePayload`
 
 ```graphql
-"""Payload returned by `workflowGraphUpdate`."""
+"""The result of `workflowGraphUpdate`."""
 type WorkflowGraphUpdatePayload {
   """
-  The updated workflow with all changes applied, or null when `errors` is non-empty.
+  The workflow with every change applied. Null when `errors` is not empty.
   """
   workflow: Workflow
-  """Validation errors. An empty array indicates success."""
+  """
+  The reasons the change set was refused, one per problem. Empty on success.
+  """
   errors: [UserError!]!
   """
-  What the author should look at on a graph that saved. The change was written;
-  each entry names a node that will not do what its author meant when the
-  workflow runs: one no path from the origin reaches, a sleep of no length, or
-  one calling an origin the project has not registered as an external API.
-  Empty when `errors` is non-empty.
+  The nodes of a saved graph that will not run as meant: a node no path from the origin reaches, a
+  sleep of no length, or an `http` call to an origin the project has not registered as an
+  external API. Empty when `errors` is not empty.
   """
   warnings: [UserError!]!
   """
-  The persisted id minted for each created node and edge. Empty when `errors` is non-empty.
+  The ID given to each created node and edge. Empty when `errors` is not empty.
   """
   idMappings: WorkflowIdMappings!
 }
@@ -919,12 +872,12 @@ type WorkflowGraphUpdatePayload {
 
 ```graphql
 """
-The persisted ids a change set's creates were given, keyed by the client ids that named them.
+The IDs given to the nodes and edges a change set created, by `clientId`.
 """
 type WorkflowIdMappings {
-  """Node id mappings, in the order the nodes were created."""
+  """The node IDs, in the order the nodes were created."""
   nodes: [IdMapping!]!
-  """Edge id mappings, in the order the edges were created."""
+  """The edge IDs, in the order the edges were created."""
   edges: [IdMapping!]!
 }
 ```
@@ -932,9 +885,9 @@ type WorkflowIdMappings {
 ### `WorkflowUpdatePayload`
 
 ```graphql
-"""Payload returned by `workflowUpdate`."""
+"""The result of `workflowUpdate`."""
 type WorkflowUpdatePayload {
-  """The updated workflow."""
+  """The workflow."""
   workflow: Workflow
 }
 ```
@@ -942,9 +895,9 @@ type WorkflowUpdatePayload {
 ### `WorkflowDeleteInput`
 
 ```graphql
-"""Input for `workflowDelete`."""
+"""The input of `workflowDelete`."""
 input WorkflowDeleteInput {
-  """Workflow ID."""
+  """The ID of the workflow."""
   id: ID!
 }
 ```
@@ -952,9 +905,9 @@ input WorkflowDeleteInput {
 ### `WorkflowDeletePayload`
 
 ```graphql
-"""Payload returned by `workflowDelete`."""
+"""The result of `workflowDelete`."""
 type WorkflowDeletePayload {
-  """ID of the deleted workflow."""
+  """The ID of the deleted workflow."""
   deletedWorkflowId: ID
 }
 ```
@@ -963,23 +916,28 @@ type WorkflowDeletePayload {
 
 ```graphql
 """
-Input for `workflowTestRun`. Supply the field the workflow's trigger takes and
-omit the other.
+The input of `workflowTestRun`. Give the field the trigger of the workflow takes, and omit the
+other.
 """
 input WorkflowTestRunInput {
-  """The workflow to test-run."""
+  """The ID of the workflow."""
   workflowId: ID!
   """
-  For an `ACTION` trigger: the answers the action carries, keyed by field key.
-  Templates and rules reach them as `trigger.action.responses.<key>`. Defaults to
-  no answers. Refused on an `EVENT` trigger.
+  The answers the action carries, keyed by field key, for an `ACTION` trigger. Templates and rules
+  read them as `trigger.action.responses.<key>`. Defaults to none. Refused for an `EVENT` trigger.
   """
   responses: JSON
   """
-  For an `EVENT` trigger: the entity the event is about, reached as
-  `trigger.entityId`. Defaults to the workflow's workspace ID.
+  The ID of the entity the event is about, for an `EVENT` trigger, read as `trigger.entityId`.
+  Defaults to the ID of the workspace.
   """
   entityId: ID
+  """
+  Whether tools that write run for real, as the workflow, as in a live run. Labels set on the run
+  are held under its `test_` ID and removed when it ends, and the test run stops after 60 seconds.
+  Defaults to false.
+  """
+  executeWrites: Boolean = false
 }
 ```
 
@@ -988,9 +946,11 @@ input WorkflowTestRunInput {
 ```graphql
 """How a test run ended."""
 enum WorkflowTestRunStatus {
-  """Every node the walk reached did its work, or held its write back."""
+  """Every node reached did its work or was skipped."""
   COMPLETED
-  """A node failed and the walk stopped there."""
+  """
+  A node failed, or a test run that executes writes passed its 60-second limit.
+  """
   FAILED
 }
 ```
@@ -1000,13 +960,16 @@ enum WorkflowTestRunStatus {
 ```graphql
 """How one task of a test run ended."""
 enum WorkflowTestRunTaskStatus {
-  """The node did its work. A tool that reads ran for real."""
+  """The node did its work. A tool that only reads ran for real."""
   SUCCEEDED
-  """The node failed, and the walk stopped there."""
+  """
+  The node failed, which stopped the test run. A tool still running at the 60-second limit is
+  `FAILED`, and its writes can still land.
+  """
   FAILED
   """
-  The tool writes, so the test run did not run it. `input` holds what it would
-  have sent; it recorded nothing, so a later node addressing it finds nothing.
+  The tool writes and the test run does not execute writes, or the tool never runs in a test run.
+  `input` holds what it would have sent, and a later node that reads its output finds nothing.
   """
   SKIPPED
 }
@@ -1015,41 +978,37 @@ enum WorkflowTestRunTaskStatus {
 ### `WorkflowTestRunTask`
 
 ```graphql
-"""
-One visit a test run made to a node. Never stored: it exists only in the payload that
-returned it.
-"""
+"""One visit of a test run to a node. It is not stored."""
 type WorkflowTestRunTask {
-  """The node's ID."""
+  """The ID of the node."""
   nodeId: ID!
   """
-  The node's place in the walk. The `ORIGIN` node is 0 and is not listed.
+  The position of the task in the test run, from 1. The `ORIGIN` node is 0 and is not listed.
   """
   index: Int!
-  """
-  Which visit of its node the task is, from 1. A walk that re-enters a node lists each visit.
-  """
+  """The number of the visit to the node, from 1."""
   visit: Int!
-  """The node's kind. Never `ORIGIN`."""
+  """The kind of node. Never `ORIGIN`."""
   type: WorkflowTaskType!
-  """The tool a `TOOL` node runs."""
+  """The tool of a `TOOL` node. Null for other kinds."""
   tool: String
   """How the task ended."""
   status: WorkflowTestRunTaskStatus!
   """
-  A `TOOL` node's arguments with every template resolved, as the tool received
-  them or, when `SKIPPED`, would have. A `SLEEP` node's `{ duration }`.
+  The arguments of a `TOOL` node with every template resolved, as the tool received them or would
+  have. For a `SLEEP` node, `{ duration }`.
   """
   input: JSON
   """
-  What a `TOOL` node recorded, in the form later nodes read it: a reference is a
-  `$ref` envelope naming the tool and what it resolves. Null when skipped.
+  The output of a `TOOL` node, as later nodes read it; a reference is a `$ref` envelope that names
+  the tool and what it resolves. An `action_response` node also carries its `payload`. Null when
+  skipped.
   """
   output: JSON
-  """The branch a `CONDITION` node took."""
+  """The branch a `CONDITION` node took. Null for other kinds."""
   branch: WorkflowEdgeHandle
   """
-  Why the task failed, naming the node, its tool and at most an argument.
+  Why the task failed, naming the node, its tool and at most one argument. Null unless it failed.
   """
   failureMessage: String
 }
@@ -1059,20 +1018,21 @@ type WorkflowTestRunTask {
 
 ```graphql
 """
-A workflow's draft graph walked once against a supplied trigger, with every
-write held back.
-
-Tools that read (`search_leads`, `http` with `GET` or `HEAD`) run for real;
-tools that write are `SKIPPED`. `SLEEP` nodes do not wait. Nothing is stored:
-no run appears in `Workflow.runs`, no operation is recorded and no event is
-published.
+One walk of the draft graph of a workflow against a given trigger. Tools that only read run for
+real, tools that write are `SKIPPED` unless the input sets `executeWrites`, and `SLEEP` nodes do
+not wait. With `executeWrites`, what the writes store and record remains.
 """
 type WorkflowTestRun {
-  """How the run ended."""
+  """How the test run ended."""
   status: WorkflowTestRunStatus!
-  """Why the run stopped, when `status` is `FAILED`."""
+  """
+  Why the test run stopped: a run failure code such as `node_failed`, or `test_run_timed_out` when
+  a test run that executes writes passed its 60-second limit. Null unless `status` is `FAILED`.
+  """
+  failureCode: String
+  """Why the test run stopped. Null unless `status` is `FAILED`."""
   failureMessage: String
-  """Every node the walk reached after the `ORIGIN`, in order."""
+  """Every node the test run reached after the `ORIGIN`, in order."""
   tasks: [WorkflowTestRunTask!]!
 }
 ```
@@ -1080,13 +1040,13 @@ type WorkflowTestRun {
 ### `WorkflowTestRunPayload`
 
 ```graphql
-"""Payload returned by `workflowTestRun`."""
+"""The result of `workflowTestRun`."""
 type WorkflowTestRunPayload {
-  """The test run, or null when `userErrors` is non-empty."""
+  """The test run. Null when `userErrors` is not empty."""
   testRun: WorkflowTestRun
   """
-  Why the input cannot start this workflow. Codes: `RESPONSES_NOT_ACCEPTED`,
-  `INVALID_RESPONSES`, `ACTION_DELETED`, `TRIGGER_UNUSABLE`.
+  The reasons the input cannot start the workflow, with codes `RESPONSES_NOT_ACCEPTED`,
+  `INVALID_RESPONSES`, `ACTION_DELETED` or `TRIGGER_UNUSABLE`.
   """
   userErrors: [UserError!]!
 }
@@ -1095,16 +1055,13 @@ type WorkflowTestRunPayload {
 ### `WorkflowSortKeys`
 
 ```graphql
-"""
-Sort keys for `workflows(...)`. Pair with `reverse: true` to flip the order
-(`NAME` + `reverse: false` sorts A→Z; `CREATED_AT` + `reverse: true` is newest-first).
-"""
+"""The orders `workflows` can sort by. `reverse: true` flips the order."""
 enum WorkflowSortKeys {
-  """Sort by `name` (alphabetical)."""
+  """By `name`, A to Z."""
   NAME
-  """Sort by `createdAt`."""
+  """By `createdAt`, oldest first."""
   CREATED_AT
-  """Sort by `updatedAt`."""
+  """By `updatedAt`, oldest first."""
   UPDATED_AT
 }
 ```