@picked/client 0.0.98-next.1 → 0.0.98-next.3

package/dist/docs/how-to/wait-for-an-action-response.md

@@ -0,0 +1,182 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to wait for the response of an action
+
+This guide shows you how to run an action from your application and show its response. You
+need an action in your project first, with a key and a workflow that the action starts. See
+[Actions](/reference/dashboard/actions).
+
+The response is the value that the action returns. For an action that starts a workflow in
+Picked, the response is the payload of the **Action response** node in the workflow.
+
+## 1. Generate the types of your project
+
+Run type generation. The generated types name the actions that start a workflow. For those
+keys, the types of `useAction` and `getAction` include `run`. At runtime, the value includes
+`run` for each key. See [Type generation](/reference/sdk/type-generation).
+
+## 2. Bind the action to a component
+
+Call `useAction` in React, or `getAction` in Svelte. Neither runs the action. The action runs
+only when you call `run`. The action receives the arguments of `run` in `args`.
+
+All the components that use the same key and the same experience share one run state. When
+one of them calls `run`, all of them show that run.
+
+:::code-group
+
+```tsx [React]
+import { useAction } from '@picked/react/hooks'
+
+function CallbackButton() {
+  const callback = useAction('request-callback')
+
+  return (
+    <button onClick={() => void callback.run()} disabled={callback.status === 'running'}>
+      Get a call back
+    </button>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getAction } from '@picked/svelte/hooks'
+
+  const callback = getAction('request-callback')
+</script>
+
+<button onclick={() => $callback.run()} disabled={$callback.status === 'running'}>
+  Get a call back
+</button>
+```
+
+:::
+
+## 3. Show the response
+
+Read `status`, `response` and `error` for the last run. Compare `response` with the values
+that your workflow sends.
+
+:::code-group
+
+```tsx [React]
+import { useAction } from '@picked/react/hooks'
+
+// Reads the status that the workflow sends in its response.
+function answerStatus(response: unknown): unknown {
+  return typeof response === 'object' && response !== null && 'status' in response
+    ? response.status
+    : undefined
+}
+
+function CallbackButton() {
+  const callback = useAction('request-callback')
+
+  if (callback.status === 'failed') return <p>We could not send your request.</p>
+  if (callback.status === 'succeeded') {
+    if (answerStatus(callback.response) === 'closed') {
+      return <p>We call back on weekdays, 8 am to 5 pm.</p>
+    }
+    return <p>Thank you. We will call you soon.</p>
+  }
+
+  return (
+    <button onClick={() => void callback.run()} disabled={callback.status === 'running'}>
+      Get a call back
+    </button>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getAction } from '@picked/svelte/hooks'
+
+  const callback = getAction('request-callback')
+
+  // Reads the status that the workflow sends in its response.
+  function answerStatus(response: unknown): unknown {
+    return typeof response === 'object' && response !== null && 'status' in response
+      ? response.status
+      : undefined
+  }
+</script>
+
+{#if $callback.status === 'failed'}
+  <p>We could not send your request.</p>
+{:else if $callback.status === 'succeeded' && answerStatus($callback.response) === 'closed'}
+  <p>We call back on weekdays, 8 am to 5 pm.</p>
+{:else if $callback.status === 'succeeded'}
+  <p>Thank you. We will call you soon.</p>
+{:else}
+  <button onclick={() => $callback.run()} disabled={$callback.status === 'running'}>
+    Get a call back
+  </button>
+{/if}
+```
+
+:::
+
+`run` does not reject. It resolves to `{ status: 'succeeded', response }` or to
+`{ status: 'failed', error }`.
+
+## 4. Run the action outside a component
+
+Call `client.actions.run` with the action key. It resolves to the response, and it rejects
+when the action fails.
+
+The client registers the actions of your project when it loads the configuration of your
+project. For this, the client must have `dynamicExperiencesPlugin`, and you must start the
+client. Until the client is ready, `run` rejects with `Action '<key>' is not registered`. A
+handler that your application registers in `createClient({ actions })` is available
+immediately.
+
+```ts
+import { createClient } from 'picked'
+import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
+
+const picked = createClient({
+  projectId: 'your-project-id',
+  plugins: [dynamicExperiencesPlugin()],
+})
+
+picked.start()
+
+// Waits until the client is ready.
+async function whenReady(): Promise<void> {
+  if (picked.readyStore.getState()) return
+
+  await new Promise<void>((resolve) => {
+    const subscription = picked.readyStore.updates.watch((ready) => {
+      if (!ready) return
+      subscription.unsubscribe()
+      resolve()
+    })
+  })
+}
+
+async function requestCallback(): Promise<void> {
+  await whenReady()
+
+  try {
+    const response = await picked.actions.run('request-callback', { timeoutMs: 15_000 })
+    console.info('Callback response', response)
+  } catch (error) {
+    console.warn('Callback request failed', error)
+  }
+}
+```
+
+Set `timeoutMs` to stop the wait sooner. Set `signal` to stop the wait from your own code.
+
+## Related
+
+- [SDK actions](/reference/sdk/actions) — every outcome, error and limit.
+- [How to register an action handler](/how-to/register-an-action-handler) — return a
+  response from your own handler.
+- [How to call an external API from a workflow](/how-to/call-an-external-api-from-a-workflow)
+  — a workflow that sends a response.

package/dist/docs/reference/dashboard/actions.mdx

@@ -24,8 +24,11 @@ not see it.
 
 ## Register in your application
 
-Each action key must match a key in the `actions` object that you pass to
-`createClient()`. See
+A published action that starts a workflow needs no code in your application. The SDK
+sends the request to Picked, and the workflow runs there.
+
+To run your own code, pass a handler under the action key in `createClient()`. That handler
+replaces the workflow for this key. See
 [How to register an action handler](/how-to/register-an-action-handler) for the code, and
 [SDK actions](/reference/sdk/actions) for what the handler receives and returns.
 

package/dist/docs/reference/dashboard/external-apis.md

@@ -10,37 +10,37 @@ An external API is an origin that this project's workflows are allowed to call w
 
 ## Registration
 
-| Field | Rule |
-| --- | --- |
-| Display name | Required. 1 to 120 characters. For you only; it does not go out with the request. |
-| Origin | Required. The scheme, the host and the optional port, with no path, query, fragment or sign-in details. `http` or `https` only, on port 80 or 443. Must not point at a private, loopback or link-local address. One live registration per origin per project. |
-| Authorization header | Optional. A header name and a value. The value is encrypted and is never returned. The dashboard shows the header name and a mask. |
+| Field                | Rule                                                                                                                                                                                                                                                          |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Display name         | Required. 1 to 120 characters. For you only; it does not go out with the request.                                                                                                                                                                             |
+| Origin               | Required. The scheme, the host and the optional port, with no path, query, fragment or sign-in details. `http` or `https` only, on port 80 or 443. Must not point at a private, loopback or link-local address. One live registration per origin per project. |
+| Authorization header | Optional. A header name and a value. The value is encrypted and is never returned. The dashboard shows the header name and a mask.                                                                                                                            |
 
 To change an origin, delete the registration and register the new origin. The origin is
 the registration's identity.
 
 ## Node arguments
 
-| Argument | Default | Rule |
-| --- | --- | --- |
-| `method` | — | Required. `GET`, `HEAD`, `POST`, `PUT`, `PATCH` or `DELETE`. |
-| `url` | — | Required. The full address. Its origin must be registered to this project. |
-| `headers` | none | A JSON object of headers to send. Picked refuses a credential here when you save. |
-| `body` | none | The JSON body. Used by `POST`, `PUT` and `PATCH`. |
-| `timeoutMs` | 10000 | 1000 to 30000. The time that the whole call has, with every retry. |
-| `retry` | on | Whether to send the request again after a timeout, a transport error, a 408 or a 429. |
-| `failOnErrorStatus` | on | Whether a status of 400 or more fails the node. |
-| `recordBody` | on | Whether to record the answer's body. |
+| Argument            | Default                                                              | Rule                                                                                                                 |
+| ------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `method`            | —                                                                    | Required. `GET`, `HEAD`, `POST`, `PUT`, `PATCH` or `DELETE`.                                                         |
+| `url`               | —                                                                    | Required. The full address. Its origin must be registered to this project.                                           |
+| `headers`           | none                                                                 | A JSON object of headers to send. Picked refuses a credential here when you save.                                    |
+| `body`              | none                                                                 | The JSON body. Used by `POST`, `PUT` and `PATCH`.                                                                    |
+| `timeoutMs`         | 10000                                                                | 1000 to 30000. The time that the whole call has, with every retry.                                                   |
+| `retry`             | on for `GET`, `HEAD`, `PUT` and `DELETE`; off for `POST` and `PATCH` | Whether to send the request again after a failed connection, an unknown host, or a status of 408, 429 or 500 to 599. |
+| `failOnErrorStatus` | on                                                                   | Whether a status outside 200 to 299 fails the node.                                                                  |
+| `recordBody`        | on                                                                   | Whether to record the answer's body.                                                                                 |
 
 ## Output
 
-| Name | Value |
-| --- | --- |
-| `status` | The HTTP status, or null when nothing answered. |
-| `ok` | True for a status below 400. |
-| `body` | The parsed JSON answer, or null when it is not JSON or was not recorded. |
-| `bodyTruncated` | True when the answer was too large to record in full. |
-| `durationMs` | The time the call took. |
+| Name            | Value                                                                    |
+| --------------- | ------------------------------------------------------------------------ |
+| `status`        | The HTTP status.                                                         |
+| `ok`            | True for a status from 200 to 299.                                       |
+| `body`          | The parsed JSON answer, or null when it is not JSON or was not recorded. |
+| `bodyTruncated` | True when the answer was too large to record in full.                    |
+| `durationMs`    | The time the call took.                                                  |
 
 ## Limits
 
@@ -50,16 +50,48 @@ the registration's identity.
   new address.
 - Picked sends a request three times at most. Picked waits longer before each retry, and
   waits for the time that a `Retry-After` header gives.
+- A timeout uses all of `timeoutMs`, so Picked does not send the request again after a
+  timeout.
 
 ## Errors
 
-| Message | Cause |
-| --- | --- |
-| `no external API is registered for <origin>` | The URL's origin has no live registration in this project. |
-| `the API answered <status>` | The status was 400 or more and `failOnErrorStatus` is on. |
-| `the API did not answer in time` | Nothing answered within `timeoutMs`. |
-| `the API could not be reached` | The connection failed. |
-| `the URL is not allowed` | The URL points at a private, loopback or link-local address. |
+When the node fails, the run stops at the node. If the call fails and an edge leaves the
+node's error exit, the run continues on that edge. These failures stop the run at the
+node, with or without that edge:
+
+- A required argument has no value.
+- An argument has a value that the tool does not accept. For example, the value has the
+  wrong type, `method` is not one of the six methods, or `timeoutMs` is not from
+  1000 to 30000.
+- A template cannot be rendered.
+- The workflow does not have a scope that the tool needs.
+- An error occurs in Picked.
+
+A later node reads why the call failed from `nodes.<node-id>.error`:
+
+| Field       | Value                                                    |
+| ----------- | -------------------------------------------------------- |
+| `code`      | `http_failed`.                                           |
+| `message`   | The node, the tool and the message from the table below. |
+| `reason`    | The reason from the table below.                         |
+| `retryable` | True when the same request can pass at a later time.     |
+| `status`    | The HTTP status, for the reason `error_status` only.     |
+
+After an error status, `nodes.<node-id>.status`, `ok` and `body` also keep the answer.
+
+| Reason                   | Message ends with                                     | Retryable                   | When                                                              |
+| ------------------------ | ----------------------------------------------------- | --------------------------- | ----------------------------------------------------------------- |
+| `error_status`           | `the API answered <status>`                           | For 408, 429 and 500 to 599 | The status was outside 200 to 299, and `failOnErrorStatus` is on. |
+| `timeout`                | `no answer within the node's timeout`                 | Yes                         | Nothing answered within `timeoutMs`.                              |
+| `transport`              | `the request could not be delivered`                  | Yes                         | The connection failed.                                            |
+| `unresolvable`           | `the destination hostname did not resolve`            | Yes                         | No address was found for the host.                                |
+| `refused`                | `the destination was refused`                         | No                          | The URL points at a private, loopback or link-local address.      |
+| `refused`                | `no external API is registered for <origin>`          | No                          | The URL's origin has no live registration in this project.        |
+| `request_too_large`      | `the request body is over 1 MiB`                      | No                          | The body is larger than the limit.                                |
+| `invalid_request`        | `the request is not one the tool can send`            | No                          | The arguments do not make a valid request.                        |
+| `invalid_request`        | `the URL is not one the tool can send`                | No                          | The tool cannot send to the URL.                                  |
+| `invalid_headers`        | The header that Picked refused                        | No                          | A header name or value is not valid for HTTP.                     |
+| `credential_unavailable` | `the credential for this external API is unavailable` | No                          | Picked cannot read the registration's authorization header.       |
 
 Picked also refuses a workflow when you save it if a node holds a credential in
 `headers`. Register the external API, and put the credential on the registration.

package/dist/docs/reference/dashboard/workflow-runs.md

@@ -22,11 +22,36 @@ you did not publish does not start runs.
 
 ## Run status
 
-| Status      | Meaning                                                                                       |
-| ----------- | --------------------------------------------------------------------------------------------- |
-| `Running`   | The run started and did not stop yet. A **Wait** node can keep a run in this status for days. |
-| `Completed` | Each node that the run reached did its work.                                                  |
-| `Failed`    | A node failed. The run stopped at that node. The run shows the reason.                        |
+| Status      | Meaning                                                                                         |
+| ----------- | ----------------------------------------------------------------------------------------------- |
+| `Running`   | The run started and did not stop yet. A **Wait** node can keep a run in this status for days.   |
+| `Completed` | Each node that the run reached did its work, or failed and the run continued on its error exit. |
+| `Failed`    | A node failed. The run stopped at that node. The run shows the reason.                          |
+
+A tool node that fails with an edge on its error exit shows `Failed` on its task. The run
+continues on that edge only when the tool itself fails:
+
+- An External API call fails. Refer to the [External APIs reference](/reference/dashboard/external-apis#errors).
+- Another tool refuses the request. For example, a label value is not a number for a
+  `number` label, or the lead does not exist.
+
+When the tool refuses the request, the error record has the code `tool_failed` and a
+reason from the tool, for example `value_invalid_for_type` or `not_found`.
+
+Other failures stop the run, with or without an edge on the error exit:
+
+- A required argument has no value.
+- An argument has a value that the tool does not accept:
+  - The value has the wrong type.
+  - The value is not one of the options.
+  - A number is not in the range that the tool accepts.
+  - A label namespace or key does not have the correct format.
+  - Two labels have the same namespace and key.
+  - A list of labels is empty.
+- A template cannot be rendered.
+- The workflow does not have a scope that the tool needs.
+- The tool gives output that is not valid.
+- An error occurs in Picked.
 
 ## Records
 

package/dist/docs/reference/dashboard/workflow-test-runs.md

@@ -51,11 +51,15 @@ A later node that reads the output of a skipped node gets no value.
 
 ## Result
 
-| Status      | Meaning                                                                   |
-| ----------- | ------------------------------------------------------------------------- |
-| `Succeeded` | The node did its work.                                                    |
-| `Skipped`   | The tool writes, so the test run did not run it.                          |
-| `Failed`    | The node failed. The test run stopped at that node, and shows the reason. |
+| Status      | Meaning                                          |
+| ----------- | ------------------------------------------------ |
+| `Succeeded` | The node did its work.                           |
+| `Skipped`   | The tool writes, so the test run did not run it. |
+| `Failed`    | The node failed, and shows the reason.           |
+
+When a node fails, the test run stops at that node and shows `Failed`. If an edge leaves
+the error exit of the node, the test run continues on that edge as a run does, and can
+show `Completed`. Refer to the [workflow runs reference](/reference/dashboard/workflow-runs#run-status).
 
 Each node shows its input and its output. A test run does not show in **Runs**, and it
 does not create or change leads or labels.

package/dist/docs/reference/delivery-api/workspace-schema.md

@@ -28,13 +28,16 @@ The response is a [JSON Schema draft 2020-12](https://json-schema.org/draft/2020
 | `x-picked-source` | `"published"` or `"preview"` — mirrors the surface you requested. |
 | `x-picked-version-id` | Published workspace version id, or `null` on preview. |
 | `x-picked-step-content-models` | Map of step key → content model key, which gives each layout its type. |
+| `x-picked-step-fields` | Map of step key → the keys of the fields on that step, in order. |
 | `x-picked-feature-values` | Map of feature key → the values that the feature can serve. Picked adds this field only when the workspace has a Text feature flag. |
+| `x-picked-workflow-action-keys` | Keys of the actions that start a workflow, sorted. Picked adds this field only when the workspace has such an action. |
 | `$defs.contentModels` | JSON Schema definitions for each content model. |
 | `$defs.contentBlocks` | JSON Schema definitions for reusable content blocks. |
 | `$defs.fields` | Object schema for project field values. |
 | `$defs.featureKeys` | String enum of feature keys. |
 | `$defs.experienceKeys` | String enum of experience keys. |
 | `$defs.stepKeys` | String enum of step keys. |
+| `$defs.actionKeys` | String enum of action keys. A schema from a version that Picked published before this field existed has none. |
 
 ## Field values
 

package/dist/docs/reference/sdk/actions.md

@@ -5,8 +5,23 @@ layout: docs
 
 # Actions
 
-Register an action handler on the Picked client. The SDK then invokes the handler
-when an experience flow reaches an action node.
+An action is a function that the SDK runs by its key. An action comes from one of two
+places:
+
+- **Your application** registers a handler in `createClient({ actions })`.
+- **Your project** publishes the action. Its handler sends the visitor's answers to Picked,
+  and the workflow of the action runs there.
+
+A handler from your application replaces a published action that has the same key. The
+workflow then does not start.
+
+## Response
+
+The value that a handler returns is the response of the action. A handler can return any
+value, or a promise of any value.
+
+The response of a published action is the payload of the **Action response** node in its
+workflow. A workflow that has no **Action response** node gives `undefined`.
 
 ## Outcome and branch
 
@@ -19,10 +34,119 @@ An action node can also carry one plain connection, with no success or failure b
 flow then continues through it on either outcome.
 
 An action does not interrupt your visitor. The current step stays on the screen while an
-async action runs.
+async action runs. While the action runs, the flow ignores a request to go to the next step
+or to a specified step. The outcome of the action then chooses the branch. If your visitor
+goes back before the action completes, the flow stays on that step. The signal that the
+handler receives then stops.
+
+## Published actions
+
+A published action waits for the response of its workflow. It stops after 30 seconds.
+
+| Cause | The action rejects with |
+| --- | --- |
+| Picked refuses the request | An `Error` that names the HTTP status |
+| Picked does not accept the request in 25 seconds | A `TimeoutError` |
+| Picked accepts the request, but gives no run to wait for | An `Error` that says that no run is available |
+| The workflow fails before it sends a response | `ActionRunFailedError` |
+| Picked refuses a request for the response with a `4xx` status | An `Error` that names the HTTP status |
+| No response in 30 seconds | `ActionResponseTimeoutError` |
+| Your code stops the wait with a signal | The reason of the signal |
+
+A request for the response can fail because of a network error, a timeout, a `5xx` status or
+a body that the SDK cannot read. The SDK then sends the request again. It waits 1 second after
+the first failure, and two times longer after each failure that follows. If the requests
+continue to fail, the 30-second limit stops the wait with `ActionResponseTimeoutError`.
+
+To identify `ActionRunFailedError` and `ActionResponseTimeoutError` with `instanceof`, import
+them from `@picked/client/plugins/dynamic-experiences`. The `name` of each error is the same
+as the name that you import.
+
+## Run an action from code
+
+| API | Returns | Rejects |
+| --- | --- | --- |
+| `client.actions.run(key, options)` | A promise of the response | Yes, with the error of the action |
+| `useAction(key, options)` (React) | For an action that starts a workflow: `{ run, status, response, error }`. For other actions: the action as a function. | `run`: No. The function: it returns or throws what the action returns or throws. |
+| `getAction(key, options)` (Svelte) | A store of the same value | The same as `useAction` |
+| `useActionResult(key, options)` (React) | The last result of your own action | No |
+| `getActionResult(key, options)` (Svelte) | A store of the last result of your own action | No |
+| `client.actions.getActionBinding(key, options)` | A store of the value that `useAction` and `getAction` give | The same as `useAction` |
+| `client.actions.getActionResult(key, options)` | A store of the last result of your own action, which `useActionResult` and `getActionResult` read | No |
+
+Type generation names the actions that start a workflow (`WorkflowActionKeys`). Without generated
+types, `useAction` and `getAction` give the action as a function. For each key, the value also
+includes `run`, `status`, `response` and `error`.
+
+The handler receives the arguments of a call to the function in `args`. It also receives the
+arguments of `run(...args)` in `args`.
+
+`status` is `idle`, `running`, `succeeded` or `failed`, for the last run. When a run starts,
+`response` and `error` are `undefined`. `run(...args)` resolves to
+`{ status: 'succeeded', response }` or to `{ status: 'failed', error }`.
+
+The SDK keeps one run state for each key and experience. All the components that use the
+same key and the same experience share that run state, and they show the same last run. When
+one of them calls `run`, all of them show that run.
+
+`useActionResult` and `getActionResult` run your own action again when a response, a field or
+the handler of the action changes. They also run it when a component that reads the result
+starts. In React, the action runs when the component mounts, and when an `<Activity>` shows the
+component again. In Svelte, it runs each time a component calls `getActionResult`. A change that
+occurs outside Picked, for example a login, then shows in a component that starts after the
+change.
+
+The components that read the same key and the same experience share one result. The action
+runs one time for each change. It also runs one time for the components that React renders
+together. React can stop while it renders and continue later, for example in a transition. Then
+the components that React renders after it continues run the action again.
+
+The result is always from the run that started last. If that run throws, the result is
+`undefined`. For a published action they give `undefined` and do not send a request. The types
+refuse the key of an action that starts a workflow.
+
+A result for an experience follows the changes only while `client.experienceInstances`
+contains that experience. When `client.experienceInstances` adds the experience, the action
+runs if a response, a field or the handler changed after the last run.
+
+The options of `client.actions.run`:
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `args` | `unknown[]` | The values that the handler receives in `args`. |
+| `experience` | `ExperienceInstance` | The experience that the handler receives as `context.experience`. |
+| `signal` | `AbortSignal` | Stops the wait. The handler receives a signal that stops too. |
+| `timeoutMs` | `number` | Stops the wait after this many milliseconds, with a `TimeoutError`. |
+
+`useAction` and `getAction` take `experience` only.
+
+## Other methods of `client.actions`
+
+| Method | Description |
+| --- | --- |
+| `refreshActionResult(key, options)` | Runs your own action again for the result that `getActionResult` gives. It does nothing until a component or your code reads that result. The calls in one task start one run. |
+| `isPublished(key)` | Returns `true` when the handler of the key is a published action. |
+| `unregister(key)` | Removes the handler of the key. If the key has no handler, nothing changes. |
+
+`refreshActionResult` and `getActionResult` take `experience` only.
+
+## Rule logic
+
+A rule reads the response of an action with `{ "invoke": [{ "var": "actions.<key>" }] }`. A
+response that is a string, a number, a Boolean, `null`, or an array or object of these
+reaches the rule. A different response reaches the rule as `undefined`.
+
+A rule runs the action each time the SDK evaluates the rule.
+
+A condition node can have a rule that runs an action. While the condition node waits for that
+rule, the flow ignores a request to go to the next step or to a specified step. The result of
+the rule then chooses the branch. If your visitor goes back before the rule has a result, the
+flow ignores the result.
 
 ## Related
 
+- [How to wait for the response of an action](/how-to/wait-for-an-action-response) — show
+  the response in a component.
 - [How to register an action handler](/how-to/register-an-action-handler) — the handler,
   and when to throw.
 - [About how Picked works](/explanation/how-picked-works#how-an-action-decides-which-way-to-go)

package/dist/docs/reference/sdk/type-generation.md

@@ -244,6 +244,14 @@ Each key type has a `Known` form that holds the workspace keys alone —
 `KnownFeatureKeys`, `KnownActionKeys`, `KnownFieldKeys`, `KnownStepKeys`, and
 `KnownExperienceKeys`. Use one where you want the workspace set and nothing else.
 
+## Actions that start a workflow
+
+`WorkflowActionKeys` holds the keys of the actions that start a workflow in the workspace. For one
+of these keys, the types of `useAction` and `getAction` give `run`, `status`, `response` and
+`error`. For every other key, the types give the action as a function. Without generated types,
+and with a schema that has no such actions, `WorkflowActionKeys` is `never`. See
+[Actions](/reference/sdk/actions).
+
 ## Cache
 
 Type generation writes its artefacts under `.picked/`: the schema JSON and a manifest. The first run adds this directory to `.gitignore` for you.