@picked/client 0.0.70-next.6 → 0.0.71-next.1

package/dist/docs/sdk/ssr/serialize.md

@@ -4,9 +4,11 @@ layout: docs
 
 # Server Snapshot
 
-`serialize()` evaluates which experiences match a URL and fetches their content on the server, returning a plain-JSON snapshot you pass to the client.
+`serialize()` finds which experiences match a URL and reads their content on the
+server. It returns a snapshot as plain JSON, and you pass that snapshot to the
+client.
 
-## serialize(client, params)
+## The `serialize(client, params)` function
 
 ```ts
 import { createClient } from '@picked/client'
@@ -20,7 +22,14 @@ const snapshot = await serialize(client, {
 })
 ```
 
-`serialize()` registers the project config on the client synchronously, evaluates each experience's condition against `attributes.location`, fetches content for the experiences whose steps reference layout content, dedupes the content blobs by id, and returns a `PickedSnapshot`. It expects a per-request client; concurrent calls on a single client are not supported.
+`serialize()` does this. It registers the project options on the client at once. It
+evaluates the condition of each experience against `attributes.location`. It reads
+the content for each experience whose steps point at layout content. It removes the
+duplicate content blobs, which it finds by their IDs. It then returns a
+`PickedSnapshot`.
+
+Give `serialize()` one client for each request. It does not support two calls at the
+same time on one client.
 
 ```ts
 serialize(client: Picked, params: SerializeParams): Promise<PickedSnapshot>
@@ -30,13 +39,15 @@ serialize(client: Picked, params: SerializeParams): Promise<PickedSnapshot>
 
 | Parameter | Type | Default | Description |
 | --- | --- | --- | --- |
-| `projectConfig` | `ProjectConfig` | required | The published or preview config to register and select against. |
-| `attributes.location` | `Partial<SerializeLocation>` | none | URL fields injected into the selection context, such as `pathname`. |
-| `getContent` | `SerializeGetContent` | runtime API | A custom content fetcher used in place of the runtime API. |
-| `previewToken` | `string` | none | Forwarded to the content fetch so preview content resolves during preview SSR. |
-| `timeoutMs` | `number` | `10000` | Per-content-fetch timeout. On timeout the blob is skipped and the render proceeds. |
+| `projectConfig` | `ProjectConfig` | required | The published options, or the preview options, to register and choose against. |
+| `attributes.location` | `Partial<SerializeLocation>` | none | The URL fields that go into the selection context, such as `pathname`. |
+| `getContent` | `SerializeGetContent` | runtime API | Your own function to read content, in place of the runtime API. |
+| `previewToken` | `string` | none | The SDK sends this with the content request, so that preview content resolves during a preview render. |
+| `timeoutMs` | `number` | `10000` | The limit for each content request. After the limit, the SDK skips that blob and continues. |
 
-`SerializeLocation` carries the plain URL fields `href`, `pathname`, `search`, `hostname`, `origin`, `protocol`, `port`, `host`, and `hash`. Pass only the ones your conditions read.
+`SerializeLocation` carries the URL fields `href`, `pathname`, `search`, `hostname`,
+`origin`, `protocol`, `port`, `host`, and `hash`. Pass only the fields that your
+conditions read.
 
 ## The snapshot
 
@@ -51,16 +62,18 @@ interface PickedSnapshot {
 
 | Field | Description |
 | --- | --- |
-| `versionId` | The project version the snapshot was selected against, or `null` when unknown (for example on preview). |
-| `projectConfig` | The config the server selected with. It travels so the client renders against the exact same config. |
-| `content` | The deduped content blobs for the selected experiences. |
-| `conditionResults` | The memoized condition results, keyed by rule hash, so the client reuses the server's selection. |
+| `versionId` | The project version that the snapshot was chosen against. It is `null` when the version is not known, for example in a preview. |
+| `projectConfig` | The options that the server chose with. They travel to the client, so that the client renders against exactly the same options. |
+| `content` | The content blobs for the chosen experiences, with the duplicates removed. |
+| `conditionResults` | The condition results that the server kept, under a key made from the rule hash. The client then reuses the choice of the server. |
 
-The snapshot is plain JSON. Serialize it into your HTML response with `JSON.stringify` and read it back on the client.
+The snapshot is plain JSON. Write it into your HTML response with `JSON.stringify`
+and read it back on the client.
 
-## Passing the snapshot to the client
+## Pass the snapshot to the client
 
-Embed the snapshot in your HTML payload, then hand it to the provider (React) or context (Svelte):
+Embed the snapshot in your HTML payload. Then give it to the provider in React, or to
+the context in Svelte:
 
 ```ts
 const html = `
@@ -69,11 +82,14 @@ const html = `
 `
 ```
 
-On the client, read `window.__PICKED__` and pass it as the `snapshot` prop. See [Rendering & Hydration](/sdk/ssr/rendering-and-hydration).
+On the client, read `window.__PICKED__` and pass it as the `snapshot` prop. See
+[Rendering and Hydration](/sdk/ssr/rendering-and-hydration).
 
-## Preview rendering
+## Render a preview
 
-Pass `previewToken` so unpublished content resolves during preview SSR. The server has no access to the request's query string, so the token cannot be recovered any other way:
+Pass `previewToken`, so that unpublished content resolves during a preview render.
+The server cannot read the query string of the request, so there is no other way to
+give it the token:
 
 ```ts
 const snapshot = await serialize(client, {
@@ -83,4 +99,6 @@ const snapshot = await serialize(client, {
 })
 ```
 
-Use the same token when you fetch `projectConfig` from the [Delivery API](/delivery-api), so the config and the content come from the same preview surface.
+Use the same token when you read `projectConfig` from the
+[Delivery API](/delivery-api). The options and the content then come from the same
+preview.

package/dist/docs/sdk/ssr/slots-and-placements.md

@@ -2,34 +2,52 @@
 layout: docs
 ---
 
-# Slots & Placements
+# Slots and Placements
 
-A slot is a named mount point. `<ExperienceSlot name="page" />` renders every experience that targets that slot and whose condition matches.
+A slot is a named mount point. `<ExperienceSlot name="page" />` renders every
+experience that points at that slot and whose condition matches.
 
 ## What a slot is
 
-A slot's `name` maps to the `.picked-slot-<name>` selector. `<ExperienceSlot name="page" />` renders every experience whose target selector is `.picked-slot-page` and whose condition is active. The slot reads each experience's active state from the seeded snapshot, so it renders synchronously during server-side rendering and the hydration first paint.
+The `name` of a slot points at the `.picked-slot-<name>` selector. So
+`<ExperienceSlot name="page" />` renders every experience with the target selector
+`.picked-slot-page`, when the condition of that experience is active.
+
+The slot reads the active state of each experience from the seeded snapshot. It
+therefore renders at once, both in server-side rendering and at the first paint of
+the hydration.
 
 ```tsx
 <ExperienceSlot name="page" />
 ```
 
-## Targeting an experience to a slot
+## Point an experience at a slot
 
-Set the experience's target selector to `.picked-slot-<name>`. An experience targeting `.picked-slot-page` renders into `<ExperienceSlot name="page" />`. The slot name and the selector suffix must match.
+Set the target selector of the experience to `.picked-slot-<name>`. An experience
+that points at `.picked-slot-page` renders into `<ExperienceSlot name="page" />`. The
+name of the slot and the end of the selector must match.
 
 ## Placement order
 
-When several experiences target the same slot, they render in placement precedence:
+When more than one experience points at the same slot, they render in this placement
+order:
 
 ```
 replace -> before -> prepend -> append -> after
 ```
 
-`replace` wins. If an active experience uses the `replace` placement, it renders alone and replaces every other match in the slot. Otherwise every active experience renders, in placement order.
+`replace` wins. An active experience with the `replace` placement renders alone, and
+it replaces every other match in the slot. In every other case each active experience
+renders, in placement order.
 
-## Multiple experiences in one slot
+## More than one experience in one slot
 
-The slot collects each experience that targets its selector, drops any whose condition is not active, and sorts the rest by placement. If a `replace` experience is among the active ones, only that experience renders. With no active `replace`, the slot renders all active experiences in `before, prepend, append, after` order.
+The slot collects each experience that points at its selector. It drops each one
+whose condition is not active. It then sorts the rest into placement order. When a `replace`
+experience is among the active ones, only that experience renders. With no active
+`replace`, the slot renders every active experience in the order `before`, `prepend`,
+`append`, `after`.
 
-This lets one Page take over a slot with `replace`, while other slots can stack several experiences by using the non-`replace` placements. Conditions decide which experiences are active; see [Conditions](/conditions).
+One Page can therefore take a whole slot with `replace`, while another slot holds
+several experiences that use the other placements. A condition decides which
+experiences are active. See [Conditions](/conditions).

package/dist/docs/sdk/steps.md

@@ -4,23 +4,33 @@ layout: docs
 
 # Steps
 
-Render steps with `<StepRouter>` and `<Step>` from `@picked/react` or `@picked/svelte`, and access the active step through `useStep()` / `getStep()`.
+Render your steps with `<StepRouter>` and `<Step>` from `@picked/react` or
+`@picked/svelte`. Reach the active step through `useStep()` or `getStep()`.
 
 ## How steps work
 
-When an experience starts, its steps are connected in a directed node graph. The SDK traverses this graph to determine which step to display:
-
-1. **Initialization**: When the experience opens, the SDK starts at the origin node and traverses the graph to find the first step
-2. **Step Entry**: The active step is set and a `step_enter` event is emitted on the event bus
-3. **Field Evaluation**: The step's fields are evaluated — fields with conditions are shown or hidden based on the current state
-4. **User Input**: The user interacts with the step's fields. Client-side validation runs on blur and on submit
-5. **Step Submission**: When the user submits, a `step_submit` event fires and field responses are committed to the client state
-6. **Navigation**: The SDK follows the edge from the current step node to the next, traversing any conditionals or actions before arriving at the next step
-7. **Completion**: When no further steps exist, the experience flow is complete
+When an experience starts, its steps form a directed graph of nodes. The SDK walks
+this graph to find which step to show:
+
+1. **Initialization**: when the experience opens, the SDK starts at the origin node.
+   It walks the graph to find the first step.
+2. **Step entry**: the SDK sets the active step. It sends a `step_enter` event on the
+   event bus.
+3. **Field evaluation**: the SDK evaluates the fields of the step. It shows or hides
+   a field with a condition, and the current state decides which.
+4. **User input**: the user fills in the fields of the step. Validation runs in the
+   browser on blur and on submit.
+5. **Step submission**: when the user submits, a `step_submit` event fires. The SDK
+   commits the field responses to the client state.
+6. **Navigation**: the SDK follows the edge from the current step node to the next
+   one. It walks through each condition and action on the way.
+7. **Completion**: when no step remains, the experience flow is complete.
 
 ## Step routing
 
-`StepRouter` listens to the experience's current step state and activates the matching `Step` by its `id`. Each `Step` registers itself on mount and unregisters on unmount, so lazy-rendered tabs or drawers work automatically.
+`StepRouter` watches the current step state of the experience. It activates the
+`Step` whose `id` matches. Each `Step` registers itself on mount and unregisters on
+unmount, so a tab or a drawer that renders lazily works with no extra code.
 
 :::code-group
 
@@ -69,12 +79,12 @@ function MyExperience() {
 :::
 
 :::note
-All Steps must be wrapped in a router, even if it is a single Step
+A router must hold every Step, even when there is only one Step.
 :::
 
 ### Lazy-loaded steps
 
-For large experiences, steps can be lazily loaded using dynamic imports:
+For a large experience, load a step lazily with a dynamic import:
 
 :::code-group
 
@@ -98,11 +108,13 @@ const WelcomeScreen = lazy(() => import('./WelcomeScreen'))
 
 :::
 
-The `component` prop accepts a `Promise<Component>` — the step's content is not loaded until it becomes active.
+The `component` prop takes a `Promise<Component>`. The SDK does not load the content
+of the step until that step becomes active.
 
-## Accessing step context
+## Reach the step context
 
-Inside a `Step` component (or any component rendered within one), call `getStep()` / `useStep()` to access the step's reactive context:
+Inside a `Step` component, or inside any component that a `Step` renders, call
+`getStep()` or `useStep()` to reach the reactive context of the step:
 
 :::code-group
 
@@ -161,24 +173,29 @@ function ContactForm() {
 
 :::
 
-`getStep()` (Svelte) / `useStep()` (React) returns a `StepContext` with the following properties:
+`getStep()` in Svelte, and `useStep()` in React, return a `StepContext` with these
+properties:
 
 | Property   | Type                                          | Description                                                                    |
 | ---------- | --------------------------------------------- | ------------------------------------------------------------------------------ |
-| `step`     | `Store<ExperienceStep>`                       | Reactive store containing the step's `id` and `label`                          |
-| `fields`   | `Store<FormField[]>`                          | Reactive store of fields with their current values, errors, and event handlers |
-| `isActive` | `Store<boolean>` (Svelte) / `boolean` (React) | Whether this step is currently active in the router                            |
-| `form`     | Object                                        | Form submission handlers (see [Forms](#forms))                                 |
+| `step`     | `Store<ExperienceStep>`                       | A reactive store that holds the `id` and the `label` of the step                |
+| `fields`   | `Store<FormField[]>`                          | A reactive store of the fields, with their current values, errors, and handlers |
+| `isActive` | `Store<boolean>` (Svelte) / `boolean` (React) | Whether the router holds this step as the active one                            |
+| `form`     | Object                                        | The handlers for a form submission. See [Forms](#forms).                        |
 
 ## Forms
 
-When a step has fields, `getStep()` / `useStep()` provides a `form` object for handling submission, validation, and navigation.
+When a step has fields, `getStep()` and `useStep()` give you a `form` object. Use it
+for the submission, the validation, and the move to the next step.
 
-Both accept an optional callbacks object — `getStep({ onSuccess })` / `useStep({ onSuccess })` — which is the recommended way to react to submission. The available slots are `onBeforeSubmit`, `onSuccess` and `onError`, all covered below.
+Both take an optional object of callbacks, as in `getStep({ onSuccess })` or
+`useStep({ onSuccess })`. This is the recommended way to act on a submission. The
+slots are `onBeforeSubmit`, `onSuccess`, and `onError`. This page covers each one
+below.
 
-### Handling submission
+### Handle a submission
 
-Bind `form.props` to your `<form>` element's `onsubmit` handler:
+Bind `form.props` to the `onsubmit` handler of your `<form>` element:
 
 :::code-group
 
@@ -242,19 +259,22 @@ function StepForm() {
 
 :::
 
-Submitting the form:
+When you submit the form, the SDK does this:
 
-1. Collects field values from the HTML form
-2. Runs `onBeforeSubmit` transform callbacks in series — a throw here aborts the submit before anything is committed
-3. Validates all required fields and field validation rules
-4. Commits the responses to the experience state
-5. Fires `form_submit_success` or `form_submit_error` on the event bus
-6. Runs your `onSuccess` or `onError` callbacks
-7. Navigates to the next step (unless `stopNavigation` is called, and regardless of whether a callback in step 6 failed)
+1. It collects the field values from the HTML form.
+2. It runs each `onBeforeSubmit` callback, one after another. A throw here aborts the
+   submit and commits nothing.
+3. It checks each required field and each validation rule.
+4. It commits the responses to the experience state.
+5. It fires `form_submit_success` or `form_submit_error` on the event bus.
+6. It runs your `onSuccess` or `onError` callback.
+7. It moves to the next step. A call to `stopNavigation` stops this. A callback that
+   failed in step 6 does not stop it.
 
-### Transforming data before submission
+### Transform data before a submission
 
-Use `onBeforeSubmit` to intercept and transform field data before it is committed. Callbacks run in series, each receiving the output of the previous:
+Use `onBeforeSubmit` to intercept and transform the field data before the SDK stores it. The callbacks run one after another. Each one takes the output of the one before
+it:
 
 :::code-group
 
@@ -264,7 +284,7 @@ Use `onBeforeSubmit` to intercept and transform field data before it is committe
 
   const { form } = getStep({
     onBeforeSubmit: async (data) => {
-      // Normalize email to lowercase before committing
+      // Normalize the email address to lowercase first.
       return {
         ...data,
         'email-address': String(data['email-address']).toLowerCase(),
@@ -282,7 +302,7 @@ import { useStep } from '@picked/react/hooks'
 function ContactStep() {
   const { form } = useStep({
     onBeforeSubmit: async (data) => {
-      // Normalize email to lowercase before committing
+      // Normalize the email address to lowercase first.
       return {
         ...data,
         'email-address': String(data['email-address']).toLowerCase(),
@@ -297,12 +317,16 @@ function ContactStep() {
 :::
 
 :::warning
-If an `onBeforeSubmit` callback throws, the submit is aborted before anything is committed and the step does not advance. This is deliberate — committing a half-transformed payload would persist wrong-but-plausible data. Use it for transforms and validation, and put side effects such as analytics or backend calls in `onSuccess` instead.
+When an `onBeforeSubmit` callback throws, the SDK aborts the submit before it commits
+anything, and the step does not advance. This is deliberate. A payload that is only
+part transformed would store data that looks correct but is wrong. Use
+`onBeforeSubmit` for a transform and for a validation check. Put a side effect, such as an
+analytics call or a backend call, in `onSuccess`.
 :::
 
 ### Success and error callbacks
 
-Pass `onSuccess` and `onError` to react to submission outcomes:
+Pass `onSuccess` and `onError` to act on the outcome of a submission:
 
 :::code-group
 
@@ -342,13 +366,20 @@ function ContactStep() {
 
 :::
 
-Callbacks are scoped to the component that passes them, and are cleaned up automatically when that component unmounts — no manual teardown is needed. Passing a new inline function on a re-render replaces the previous one rather than adding another, so a single submit runs each callback exactly once.
+A callback belongs to the component that passes it. The SDK releases the callback
+when that component unmounts, so you write no teardown code. A new inline function on
+a re-render replaces the earlier one and does not add a second one. One submit
+therefore runs each callback exactly one time.
 
-A throwing or rejecting `onSuccess`/`onError` callback cannot block the flow: the step still advances, and the failure is reported on the client event bus as `form_submit_callback_error` so it stays observable.
+An `onSuccess` or `onError` callback that throws or rejects cannot stop the flow. The
+step still advances, and the SDK reports the failure on the client event bus as
+`form_submit_callback_error`, so the failure stays observable.
 
-#### Registering callbacks imperatively
+#### Register a callback in code
 
-`form.onSuccess`, `form.onError` and `form.onBeforeSubmit` are also available as an escape hatch, for cases where a callback has to be attached conditionally. They return nothing — cleanup is automatic, as above.
+`form.onSuccess`, `form.onError`, and `form.onBeforeSubmit` are an escape hatch, for
+a callback that you must attach only when a condition holds. They return nothing. The
+SDK releases them for you, as above.
 
 ```tsx [React]
 function ContactStep({ trackConversions }: { trackConversions: boolean }) {
@@ -363,12 +394,17 @@ function ContactStep({ trackConversions }: { trackConversions: boolean }) {
 ```
 
 :::warning
-Register from the component body, not from an event handler. A registration made inside a click handler is added each time the handler runs and is only released when the component unmounts, so it accumulates. Prefer the options object above wherever you can.
+Register from the body of the component, and not from an event handler. A
+registration inside a click handler is added each time the handler runs, and the SDK
+releases it only when the component unmounts. The registrations therefore accumulate.
+Use the options object above where you can.
 :::
 
-### Preventing navigation on success
+### Stop the move to the next step
 
-By default, the experience advances to the next step after a successful submission. Call `stopNavigation()` inside `onSuccess` to prevent this, for example when you need to handle navigation manually:
+By default the experience advances to the next step after a successful submission.
+Call `stopNavigation()` inside `onSuccess` to stop this. Do it when you must choose
+the next step yourself:
 
 :::code-group
 
@@ -383,7 +419,7 @@ By default, the experience advances to the next step after a successful submissi
     onSuccess: ({ data, stopNavigation }) => {
       stopNavigation()
 
-      // Navigate to step based on submitted data
+      // Choose the next step from the data that the user sent.
       if (data['plan-type'] === 'enterprise') {
         experience.goToStepById('enterprise-contact')
       } else {
@@ -407,7 +443,7 @@ function PlanStep() {
     onSuccess: ({ data, stopNavigation }) => {
       stopNavigation()
 
-      // Decide the next step based on submitted data
+      // Choose the next step from the data that the user sent.
       if (data['plan-type'] === 'enterprise') {
         experience.goToStepById('enterprise-contact')
       } else {
@@ -422,13 +458,22 @@ function PlanStep() {
 
 :::
 
-Navigate by step `id` with `goToStepById('<step-id>')`, or by the step's semantic `key` with `goToStepByKey('<step-key>')`. Both jump straight to the matching step node; if no step matches, the call is a no-op.
+Move by step `id` with `goToStepById('<step-id>')`, or by the `key` of the step with
+`goToStepByKey('<step-key>')`. Both jump directly to the step node that matches. When
+no step matches, the call does nothing.
 
 ## Best practices
 
-- **Give steps meaningful labels**: The `label` is used in analytics events and the dashboard — prefer descriptive names like `"Contact Details"` over `"Step 2"`
-- **Keep steps focused**: Each step should collect a small, related set of information. Prefer more steps over longer forms to reduce abandonment
-- **Use conditionals for branching**: Avoid duplicating steps — model branching logic with `nextConditional()` so shared steps can be reused
-- **Use `stopNavigation` sparingly**: Automatic navigation after submit is the expected behavior. Only disable it when you need explicit control over the next destination
-- **Validate eagerly on blur, not on change**: The SDK follows this pattern automatically — fields show errors after the user leaves them, not as they type
-- **Lazy-load large step components**: Use the `component` prop on `<Step>` with a dynamic import for content that is only shown to a subset of users
+- **Give each step a meaningful label**: analytics events and the dashboard both show
+  the `label`. Use a name that says what the step does, such as `"Contact Details"`
+  and not `"Step 2"`.
+- **Keep each step small**: each step must collect one small set of related
+  information. More steps with fewer fields each reduce the number of users who leave.
+- **Use a condition to take a branch**: do not make a second copy of a step. Write the
+  branch with `nextConditional()`, so that you can reuse a shared step.
+- **Use `stopNavigation` only when you must**: an automatic move after a submit is
+  what a user expects. Stop it only when you must choose the next step yourself.
+- **Check a field on blur, not on change**: the SDK does this for you. A field shows
+  an error after the user leaves it, and not while the user types.
+- **Load a large step component lazily**: use the `component` prop on `<Step>` with a
+  dynamic import, for content that only some users see.

package/dist/docs/steps.mdx

@@ -6,7 +6,8 @@ import { Screenshot } from '../../components/Screenshot'
 
 # Steps
 
-A step is a visual screen or card shown to visitors during an experience. Each step holds one or more fields that collect data or display content.
+A step is one screen or card that a visitor sees during an experience. Each step
+holds one or more fields. A field collects data or shows content.
 
 <Screenshot
   route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/steps"
@@ -18,27 +19,35 @@ A step is a visual screen or card shown to visitors during an experience. Each s
 1. Open your project.
 2. Click **Steps** in the sidebar.
 3. Click **New Step**.
-4. Enter a name and key.
+4. Enter a name and a key.
 5. Click **Create**.
 
-The key is a unique identifier used in your application. It's set once and can't be changed later.
+The key is a unique identifier for your application. You set it once, and you cannot
+change it later.
 
-## Configure a step
+## Set up a step
 
-**Name**: The display name shown in the dashboard. Not visible to visitors.
+**Name**: The name that the dashboard shows. Your visitors do not see it.
 
-**Key**: The programmatic identifier used by your application to reference this step. Not visible to visitors.
+**Key**: The identifier that your application uses for this step. Your
+visitors do not see it.
 
-**Layout Name**: The name of the component layout used to render this step. For example, `card`, `modal`, or `fullscreen`.
+**Layout Name**: The name of the component layout that renders this step. Examples
+are `card`, `modal`, and `fullscreen`.
 
-A step can also carry a **Step Layout**, a reusable CMS schema that backs the step with a Content Entry. See [Page & Step Layouts](/content/layouts).
+A step can also carry a **Step Layout**. A step layout is a reusable CMS schema, and
+it gives the step a Content Entry. See [Page and Step Layouts](/content/layouts).
 
 ## Assign fields
 
-In the flow builder, drag a field from the entity browser onto a step node. The field appears in the step's **Assigned Fields** list in the inspector.
+In the flow builder, drag a field from the entity browser onto a step node. The field
+appears in the **Assigned Fields** list of the step, in the inspector.
 
-You can also view and manage assigned fields by selecting the step node and expanding the **Assigned Fields** section. Click any field to open its inspector.
+You can also choose the step node and expand the **Assigned Fields** section to see
+and control the assigned fields. Click a field to open its inspector.
 
 ## Reuse steps
 
-Steps are project-level entities. You can drag the same step into multiple experience flows. Changes to a step's configuration apply everywhere it's used.
+A step is a project-level entity. You can drag the same step into more than one
+experience flow. A change to the options of a step applies at every place that uses
+it.

package/dist/docs/team-management.md

@@ -4,13 +4,16 @@ layout: docs
 
 # Team management
 
-Manage who has access to your organization and what they can do. Organizations are the top-level container for projects and members.
+Control who can reach your organization and what each person can do. An organization
+is the top-level container for your projects and members.
 
 ## Organizations
 
-An organization groups your projects, members, and settings. You can belong to multiple organizations.
+An organization groups your projects, your members, and your settings. You can belong
+to more than one organization.
 
-Switch between organizations using the organization selector in the top of the sidebar.
+To move between organizations, use the organization control at the top of the
+sidebar.
 
 ## Invite members
 
@@ -18,23 +21,26 @@ Switch between organizations using the organization selector in the top of the s
 2. Click **Members**.
 3. Click **Invite**.
 4. Enter an email address.
-5. Select a role.
+5. Choose a role.
 6. Click **Send Invite**.
 
-The invited user receives an email with a link to join your organization. They need to create a Picked account if they don't have one.
+The person that you invite receives an email with a link to join your organization.
+A person without a Picked account must create one first.
 
 ## Remove members
 
 1. Open your organization.
 2. Click **Members**.
-3. Find the member you want to remove.
-4. Click **Remove** next to their name.
-5. Confirm the removal.
+3. Find the member that you want to remove.
+4. Click **Remove** next to the name of the member.
+5. Confirm.
 
-The member immediately loses access to all projects in the organization.
+The member loses access to every project in the organization immediately.
 
 ## Roles and permissions
 
-Members are assigned roles that control what they can access. Roles determine whether a member can create projects, edit experiences, manage other members, or view reports.
+Each member holds a role, and the role controls what the member can reach. A role
+decides whether a member can create a project, edit an experience, control other
+members, or read a report.
 
-Assign the minimum role needed for each member's responsibilities.
+Give each member the smallest role that the work of that member needs.