@picked/client 0.0.70-next.5 → 0.0.70

package/dist/docs/api/pagination.md

@@ -4,11 +4,13 @@ layout: docs
 
 # Pagination
 
-The Picked API uses Relay-style cursor-based pagination for all list fields that may return large result sets. This guide explains the connection pattern and demonstrates how to paginate through results.
+The Picked API paginates every list field that can return a large result. It uses a
+cursor, in the Relay-style pattern. This guide covers the connection pattern and
+shows how to move through a result.
 
 ## Connection pattern
 
-Paginated fields return a **connection** object with the following shape:
+A paginated field returns a **connection** object with this shape:
 
 ```graphql
 type ExampleConnection {
@@ -32,20 +34,21 @@ type PageInfo {
 
 | Field | Description |
 |-------|-------------|
-| `edges` | An ordered list of edges, each containing a `cursor` and a `node` (the actual data object) |
-| `pageInfo.hasNextPage` | `true` if more results exist after the last edge |
-| `pageInfo.hasPreviousPage` | `true` if results exist before the first edge |
-| `pageInfo.startCursor` | Cursor of the first edge in the current page |
-| `pageInfo.endCursor` | Cursor of the last edge in the current page |
-| `totalCount` | Total number of items across all pages |
+| `edges` | An ordered list of edges. Each edge holds a `cursor` and a `node`, and the `node` holds the data. |
+| `pageInfo.hasNextPage` | `true` when more results come after the last edge |
+| `pageInfo.hasPreviousPage` | `true` when results come before the first edge |
+| `pageInfo.startCursor` | The cursor of the first edge on the current page |
+| `pageInfo.endCursor` | The cursor of the last edge on the current page |
+| `totalCount` | The number of items on every page together |
 
 ## Forward pagination with `first` and `after`
 
-To paginate forward through results, use the `first` argument to specify the page size and the `after` argument to specify the cursor to start after.
+To move forward through the results, use two arguments. The `first` argument gives
+the page size. The `after` argument gives the cursor to start after.
 
 ### First page
 
-Omit the `after` argument to fetch the first page:
+Leave the `after` argument out to read the first page:
 
 ```graphql
 query {
@@ -89,16 +92,17 @@ query {
 }
 ```
 
-## Checking for more pages
+## Check for more pages
 
-Before requesting the next page, check the `hasNextPage` field:
+Read the `hasNextPage` field before you ask for the next page:
 
-- `hasNextPage: true` — more results are available; pass `endCursor` to the next request's `after` argument
-- `hasNextPage: false` — all results have been fetched; stop paginating
+- `hasNextPage: true` — more results are available. Pass `endCursor` as the `after`
+  argument of the next request.
+- `hasNextPage: false` — you read every result. Stop here.
 
 ## Full paginated query example
 
-The following example fetches all members of an organization, page by page:
+This example reads every member of an organization, one page at a time:
 
 ```graphql
 # Page 1
@@ -154,7 +158,8 @@ Continue until `hasNextPage` returns `false`.
 
 ## Paginated fields
 
-The following fields in the schema return connection types and support `first`/`after` pagination:
+These fields in the schema return a connection type. They all take the `first` and
+`after` arguments:
 
 | Parent Type | Field | Connection Type |
 |------------|-------|----------------|
@@ -170,7 +175,12 @@ All of these fields accept the same `first` and `after` arguments and return the
 
 ## Tips
 
-- **Default page size** — if `first` is omitted, the API applies a default limit. Explicitly setting `first` ensures predictable page sizes.
-- **Cursors are opaque** — cursor strings should be treated as opaque tokens. Do not parse, construct, or modify them. Pass them exactly as received from the API.
-- **Stable ordering** — results within a connection are returned in a stable order. The same cursor always refers to the same position in the result set.
-- **Combine with other fields** — pagination arguments can be used alongside other query fields. For example, fetching an organization and its first page of members in a single request is common and efficient.
+- **The default page size** — the API applies a default limit when you leave `first`
+  out. Set `first` yourself to make sure that each page has the size you expect.
+- **A cursor is opaque** — treat a cursor string as an opaque token. Do not parse it,
+  build it, or change it. Pass it back exactly as the API gave it.
+- **The order is stable** — a connection returns its results in a stable order. The
+  same cursor always points at the same position in the result.
+- **Use them with other fields** — you can use the pagination arguments together with
+  other query fields. One request that reads an organization and the first page of
+  its members is common, and it is efficient.

package/dist/docs/api-keys.mdx

@@ -6,7 +6,8 @@ import { Screenshot } from '../../components/Screenshot'
 
 # API keys
 
-API keys let you access Picked's API programmatically. Use them for server-side integrations or CI/CD workflows.
+An API key lets your code reach the Picked API. Use one for a server-side integration
+or for a CI/CD workflow.
 
 <Screenshot
   route="/{orgSlug}/api-keys"
@@ -21,11 +22,12 @@ API keys let you access Picked's API programmatically. Use them for server-side
 4. Enter a description.
 5. Click **Create**.
 
-Copy the key immediately — it won't be shown again.
+Copy the key immediately. The dashboard does not show it again.
 
-## Using an API key
+## Use an API key
 
-Include your API key in the `Authorization` header when making requests to the [Picked API](/api).
+Put your API key in the `Authorization` header of each request to the
+[Picked API](/api).
 
 ```
 Authorization: Bearer your-api-key
@@ -33,8 +35,11 @@ Authorization: Bearer your-api-key
 
 ## Scopes
 
-API keys can be scoped to limit what they can access. When creating a key, select the scopes that match your integration's needs. A key can only perform actions allowed by its assigned scopes.
+An API key carries scopes, and the scopes limit what the key can reach. Choose the
+scopes that your integration needs when you create the key. A key can do only the
+operations that its scopes permit.
 
 ## Revoke a key
 
-Revoke a key at any time from the API keys list. Click the revoke button next to the key you want to disable. Revoked keys stop working immediately.
+You can revoke a key at any time from the API keys list. Click the revoke button next
+to the key. A revoked key stops work immediately.

package/dist/docs/chrome-extension.md

@@ -4,17 +4,21 @@ layout: docs
 
 # Chrome Extension
 
-The Picked Developer Tools extension adds a Picked panel to Chrome DevTools for inspecting and debugging your Picked integration on any page running the SDK.
+The extension for the Picked Developer Tools adds a Picked panel to Chrome DevTools.
+Use the panel to check and debug your Picked integration on any page that runs the
+SDK.
 
 ![Picked Developer Tools](/chrome-extension-screenshot.jpg)
 
 ## Installation
 
-Install from the [Chrome Web Store](https://chromewebstore.google.com/detail/picked-developer-tools/nimmdamgnhlhdpngnalkpmnleebngidh).
+Install the extension from the
+[Chrome Web Store](https://chromewebstore.google.com/detail/picked-developer-tools/nimmdamgnhlhdpngnalkpmnleebngidh).
 
 ## Setup
 
-Add the `svelteDevtoolsPlugin` to your Picked client so the extension can connect to the SDK.
+Add the `svelteDevtoolsPlugin` to your Picked client. The extension then connects to
+the SDK.
 
 ```typescript
 import { createPicked } from '@picked/client'
@@ -30,7 +34,16 @@ const picked = createPicked({
 
 ## Custom Tools
 
-You can extend the Developer Tools with your own project-specific tools, surfaced under a **Custom Tools** tab. Each tool is a framework-adapted component — authored with the same `adaptReactComponent` / `adaptSvelteComponent` helpers you already use — so you can build it in your app's framework and it receives the live Picked client exactly like an experience component does (React: `usePicked()`; Svelte: `getPicked()`). Tools can both read client state and call client methods.
+You can extend the Developer Tools with your own tools for one project. They appear
+under a **Custom Tools** tab.
+
+Each tool is a framework-adapted component. Write it with the same
+`adaptReactComponent` or `adaptSvelteComponent` helper that you already use. You can
+therefore build the tool in the framework of your application.
+
+The tool receives the live Picked client, exactly as an experience component does. In
+React, use `usePicked()`. In Svelte, use `getPicked()`. A tool can read client state
+and call client methods.
 
 ```typescript
 import { createPicked } from '@picked/client'
@@ -48,4 +61,8 @@ const picked = createPicked({
 })
 ```
 
-The Developer Tools shell is rendered with Svelte, so a tool's framework must also be registered on the client. A React app needs `reactFrameworkPlugin` (for the tool) alongside the Svelte framework and `svelteDevtoolsPlugin` (for the shell). If a tool's framework isn't registered, its tab shows a warning instead of rendering.
+Svelte renders the Developer Tools shell, so you must also register the framework of
+your tool on the client. A React application needs `reactFrameworkPlugin` for the
+tool, together with the Svelte framework and `svelteDevtoolsPlugin` for the shell.
+When the framework of a tool is not registered, the tab of that tool shows a warning
+and no content.

package/dist/docs/conditions.mdx

@@ -6,7 +6,8 @@ import { Screenshot } from '../../components/Screenshot'
 
 # Conditions
 
-A condition evaluates logic and branches the flow into two paths — one for when the condition is true, another for when it's false.
+A condition evaluates a rule and splits the flow into two paths. One path is for a
+true result, the other for a false result.
 
 <Screenshot
   route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/conditions"
@@ -18,42 +19,54 @@ A condition evaluates logic and branches the flow into two paths — one for whe
 1. Open your project.
 2. Click **Conditions** in the sidebar.
 3. Click **New Condition**.
-4. Enter a name and key.
+4. Enter a name and a key.
 5. Click **Create**.
 
-## Configure a condition
+## Set up a condition
 
-**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. Set once, can't change. Not visible to visitors.
+**Key**: The identifier for your application. You set it once and you cannot change
+it. Your visitors do not see it.
 
-## Define logic
+## Define the rule
 
-Select a condition node in the flow builder to open its inspector. The **Logic** section contains a visual [condition builder](/flow-builder/condition-builder).
+Choose a condition node in the flow builder to open its inspector. The **Logic**
+section holds a visual [condition builder](/flow-builder/condition-builder).
 
-The condition builder lets you create rules using AND/OR groups. Each rule compares a data source against an operator and a target value.
+The condition builder lets you write a rule with AND groups and OR groups. Each rule
+compares a data source against an operator and a value.
 
-### Available data sources
+### Data sources
 
-**Responses** — values visitors have submitted through form fields. For example, check if a visitor entered a specific email domain or selected a particular option.
+**Responses** — the values that your visitors send through form fields. An example is
+a check of whether a visitor entered one email domain, or chose one option.
 
-**Actions** — references to actions that have been triggered during the flow.
+**Actions** — the actions that ran during the flow.
 
-**Feature flags** — the state of feature flags in your project. Branch on whether a visitor is allocated to a flag.
+**Feature flags** — the state of each feature flag in your project. Branch on whether
+Picked allocates a visitor to a flag.
 
-**Location** — properties of the visitor's current page URL, including pathname, search parameters, hostname, and hash. For example, show different content based on which page the visitor is on.
+**Location** — the parts of the current page URL of the visitor. These are the
+pathname, the search parameters, the hostname, and the hash. An example is content
+that changes with the page that the visitor is on.
 
 ### Example
 
-To branch based on a visitor's country selection:
+To take a branch on the country that a visitor chooses:
 
 1. Add a rule: **Responses → country** equals `US`.
-2. The green (true) path handles US visitors. The red (false) path handles everyone else.
+2. The green path, for a true result, handles a visitor in the US. The red path, for
+   a false result, handles every other visitor.
 
-To combine multiple conditions, create an AND or OR group and add rules within it.
+To join more than one rule, create an AND group or an OR group and add the rules
+inside it.
 
-## Branching
+## Branches
 
-In the flow builder, condition nodes have two output handles. The green handle (true) leads to the path taken when the condition matches. The red handle (false) leads to the alternative path.
+In the flow builder, a condition node has two output handles. The green handle, for a
+true result, leads to the path for a match. The red handle, for a false result, leads
+to the other path.
 
-You can chain conditions. Connect the output of one condition to the input of another to create complex decision trees.
+You can chain conditions. Connect the output of one condition to the input of another
+to build a decision tree.

package/dist/docs/content/asset-library.mdx

@@ -6,88 +6,119 @@ import { Screenshot } from '../../../components/Screenshot'
 
 # Asset Library
 
-The Asset Library stores the files your content references: images, video, documents, and HTML.
+The Asset Library holds the files that your content points at. These are images,
+video, documents, and HTML.
 
 <Screenshot
   route="/{orgSlug}/{projectId}/assets"
   alt="The asset library on the Picked dashboard"
 />
 
-## Upload and manage assets
+## Upload and control your assets
 
-The Asset Library is a project-level store. Upload a file, then reference it from any Content Entry in the project.
+The Asset Library is a project-level store. Upload a file, then point at it from any
+Content Entry in the project.
 
-- **Size limit:** 50 MB per file.
-- **Allowed types:** images (PNG, JPEG, WebP, AVIF, GIF, SVG), video (MP4, WebM), common document formats, and HTML (`text/html`).
+- **Size limit:** 50 MB for each file.
+- **Allowed types:** an image in PNG, JPEG, WebP, AVIF, GIF, or SVG. A video in MP4
+  or WebM. A common document format. HTML, as `text/html`.
 
-Uploads outside the allowed types or over the size limit are rejected at upload time.
+Picked rejects a file of another type. It also rejects a file above the size limit.
 
 ## Reference an asset from a field
 
-Two field types point at library items:
+Two field types point at an item in the library:
 
-- An **Asset** field references an image, video, or document.
-- An **HTML asset** field references an uploaded `.html` file.
+- An **Asset** field points at an image, a video, or a document.
+- An **HTML asset** field takes a `.html` file from your library.
 
-Add the field to a [layout](/content/layouts), then pick a library item when filling in the [Content Entry](/content/content-entries).
+Add the field to a [layout](/content/layouts). Then choose an item from the library
+when you fill in the [Content Entry](/content/content-entries).
 
 ## Pick an asset
 
-Every Asset field opens the same picker: click **Choose file** (or **Replace** on a field that already has a value) to open a modal with two tabs, **Library** (browse existing assets) and **Upload** (add a new file).
+Every Asset field opens the same picker. Click **Choose file** to open it. On a field
+with a value already, click **Replace**. The modal has two tabs: **Library**, where
+you browse the assets that are there, and **Upload**, where you add a new file.
 
 <Screenshot
   route="/{orgSlug}/{projectId}/design-systems/new"
   wait='button:has-text("Upload file")'
   click='button:has-text("Upload file")'
   selector="[role=dialog]"
-  alt="The asset picker modal on the Picked dashboard, showing the Library tab with its search box, type filter, and Sort by menu"
+  alt="The asset picker modal on the Picked dashboard, with the Library tab, its search box, its type filter, and its Sort by menu"
   renderWidth={1072}
   renderHeight={790}
 />
 
 ### Search, filter, and sort
 
-The Library tab has three controls for narrowing a large asset list, all applied on the server across the whole library, not just the assets already loaded:
+The Library tab has three controls that make a large asset list smaller. The server
+applies each one across the whole library, and not only across the assets that it
+loaded already:
 
-- **Search:** filters by file name as you type.
-- **Type filter:** narrows to a media-type bucket (All types, Images, Video, Audio, Documents, or Archives).
-- **Sort by:** orders by Name or Date uploaded, each ascending or descending.
+- **Search:** narrows the list by file name while you type.
+- **Type filter:** narrows the list to one media type. The choices are All types,
+  Images, Video, Audio, Documents, and Archive files.
+- **Sort by:** orders the list by the Name or by the Date uploaded, each one
+  ascending or descending.
 
 :::note
-Results are paginated. Use **Load more** at the bottom of the list to fetch the next page.
+The results come one page at a time. Click **Load more** at the bottom of the list to
+read the next page.
 :::
 
-### Select one or several assets
+### Choose one asset or several
 
-The picker adapts to how many assets the field accepts:
+The picker changes with the number of assets that the field takes:
 
-- A field that holds a single asset (a layout's Asset field, or a design system's guidance file) shows a **radio** indicator next to each row. Picking a new asset replaces the current one.
-- A surface that accepts several assets at once (for example, a workbench's Files tab) shows a **checkbox** indicator and a running selection count in the detail panel.
+- A field that holds one asset shows a **radio** indicator next to each row. The
+  Asset field of a layout and the guidance file of a design system both do this. A
+  new choice replaces the current asset.
+- A place that takes several assets at once shows a **checkbox** indicator. The
+  detail panel then also shows a count of what you chose. The Files tab of a
+  workbench does this.
 
-The detail panel on the right shows the selected asset's kind, dimensions, size, and upload date.
+The detail panel on the right shows the kind, the dimensions, the size, and the
+upload date of the asset that you chose.
 
 ### Open an asset in a new tab
 
-Each row, and the detail panel for the currently selected asset, has an **Open in new tab** control. It links to the asset's full detail page without losing your current selection in the picker.
+Each row has an **Open in new tab** control, and so does the detail panel of the
+asset that you chose. It links to the full detail page of the asset, and your choice
+in the picker stays as it is.
 
 :::tip
-Use this to double-check an asset (its full-size preview, every uploaded version) before committing to it.
+Use this to check an asset again before you choose it. You can see the full-size
+preview and every version that somebody uploaded.
 :::
 
 ## HTML assets
 
-Upload a `.html` file and reference it from an **HTML asset** field. On upload, Picked runs an advisory scan that guides you but never blocks the upload. It surfaces performance, SEO, and accessibility findings so you can improve the file before publishing:
+Upload a `.html` file and point at it from an **HTML asset** field. Picked then scans
+the file. The scan is advisory: it helps you, and it never stops you. It
+reports findings about speed, about search rank, and about accessibility, so that you
+can improve the file before you publish it:
 
-- **File size:** a warning at 100 KB and a stronger one at 250 KB.
-- **Inline images:** a note when inline base64 image data adds roughly 50 KB or more.
-- **Image dimensions:** images missing an explicit width or height, which risk layout shift.
-- **Lazy loading:** images without `loading="lazy"`.
-- **Link safety:** external links with `target="_blank"` but no `rel="noopener"`.
-- **Link SEO:** external links without `rel="nofollow"`.
-- **Accessibility:** an axe-core pass covering alt text, heading order, contrast, and more.
+- **File size:** a warning at 100 KB, and a stronger one at 250 KB.
+- **Inline images:** a note when inline `base64` image data adds about 50 KB or more.
+- **Image dimensions:** an image with no width and no height. Such an image can move
+  the content around it while the page loads.
+- **Lazy load:** an image with no `loading="lazy"` attribute.
+- **Link safety:** an external link with `target="_blank"` and no `rel="noopener"`.
+- **Link search rank:** an external link with no `rel="nofollow"`.
+- **Accessibility:** a pass by `axe-core`. It covers alt text, heading order,
+  contrast, and more.
 
-Every finding is advisory. You can always upload the file as is.
+Every finding is advisory. You can always upload the file as it is.
 
 ## How assets are served
 
-Assets are served from a sandboxed storage origin, separate from your app's trusted origin. Serving HTML from its own origin means an uploaded document executes in isolation and cannot reach the page that embeds it. When an [Experience Content](/delivery-api/experience-content) response includes an HTML asset, its content is inlined into the response, so the SDK renders it without a second storage fetch.
+Picked serves each asset from a sandboxed storage origin. That origin is separate
+from the trusted origin of your application. HTML therefore comes from its own
+origin, so a document that you upload runs in isolation and cannot reach the page
+that holds it.
+
+An [Experience Content](/delivery-api/experience-content) response can hold an HTML
+asset. The response then carries the content of that asset, and the SDK renders it
+with no second request to storage.

package/dist/docs/content/content-entries.mdx

@@ -23,8 +23,14 @@ A [Page](/content/pages) has a single Step, and that Step links to its entry thr
 
 ## Edit entry data
 
-The entry editor renders a form driven by the layout schema: one input per field, in the order the schema defines. Repeatable fields appear as sortable lists you can add to and reorder. Group fields nest their inputs under a single heading.
+The entry editor renders a form from the layout schema. There is one input for each
+field, in the order that the schema sets. A repeatable field appears as a sortable
+list. You can add to that list and put it into a new order. A group field holds its
+inputs under one heading.
 
 ## Validation
 
-Invalid data surfaces as per-field errors using a JSON-path style that points at the exact location in the entry, for example `sections[0].data.title`. Fix every error before publishing: the published surface only serves valid content.
+Invalid data appears as an error on each field. The error carries a path in the JSON
+style, and it points at the exact place in the entry, for example
+`sections[0].data.title`. Fix every error before you publish, because Picked serves
+valid content only.

package/dist/docs/content/layouts.mdx

@@ -15,23 +15,31 @@ Layouts are reusable JSON schemas. Page Layouts back standalone Pages; Step Layo
 
 ## What a layout is
 
-A layout is a reusable schema that defines the fields a piece of content can hold. It holds no data itself: a [Content Entry](/content/content-entries) instantiates the layout and fills it in. The dashboard groups both kinds of layout under **Models**.
+A layout is a reusable schema. It defines the fields that a piece of content can
+hold. A layout holds no data itself. A [Content Entry](/content/content-entries)
+creates one copy of a layout and fills it in. The dashboard shows both layout kinds
+under **Models**.
 
-## Page layouts vs step layouts
+## A page layout and a step layout
 
-A layout has a fixed category that decides what it backs:
+Each layout has a fixed category, and the category decides what the layout gives its
+shape to:
 
-| Layout | Backs | Used by |
+| Layout | It gives its shape to | Who renders it |
 | --- | --- | --- |
-| **Page Layout** | A standalone [Page](/content/pages). | The SDK renders the bound entry on your server. |
-| **Step Layout** | A single [Step](/steps) inside a Flow. | The Step renders the bound entry in the browser. |
+| **Page Layout** | A standalone [Page](/content/pages). | The SDK renders the entry on your server. |
+| **Step Layout** | One [Step](/steps) inside a Flow. | The Step renders the entry in the browser. |
 
 ## Create a layout
 
-1. Open your workspace and click **Models** in the sidebar.
-2. Click **New Model** and choose the category, **Page Layout** or **Step Layout**.
-3. Enter a name and a **Key**. The Key is a unique, stable identifier used in SDK code and API references.
-4. Add fields (see below) and save.
+1. Open your workspace.
+2. Click **Models** in the sidebar.
+3. Click **New Model**.
+4. Choose the category, **Page Layout** or **Step Layout**.
+5. Enter a name and a **Key**. The Key is a unique, stable identifier. Your SDK code
+   and your API calls both use it.
+6. Add your fields. See below.
+7. Save.
 
 The category is fixed at creation and cannot be changed later.
 
@@ -41,30 +49,38 @@ A layout is built from fields. Each field has a type that decides its editor and
 
 | Type | Stores | Use it for |
 | --- | --- | --- |
-| **Single-line text** | A short string. | Titles, labels, short headlines. |
-| **Multi-line text** | A longer plain string. | Descriptions, paragraphs without formatting. |
-| **Markdown** | A Markdown string. | Rich body copy with formatting. |
-| **Slug** | A URL-safe string. | Path segments, identifiers. |
-| **Number** | A numeric value. | Prices, counts, ratings. |
-| **Boolean** | A true/false value. | Toggles, flags. |
-| **Date** | A date value. | Publish dates, deadlines. |
-| **Color** | A color value. | Theme accents, swatches. |
-| **JSON** | An arbitrary JSON value. | Structured data with no dedicated editor. |
-| **Group** | A nested object of fields. | Grouping related fields together. |
-| **Section** | An embedded [Section](/content/sections) schema. | Reusing a shared schema fragment. |
-| **Asset** | A reference to an [Asset Library](/content/asset-library) item. | Images, video, documents. |
-| **HTML asset** | A reference to an uploaded `.html` file. | Pre-built HTML embedded into content. |
+| **Single-line text** | A short string. | A title, a label, or a short headline. |
+| **Multi-line text** | A longer plain string. | A description, or a paragraph with no format marks. |
+| **Markdown** | A Markdown string. | Body copy with format marks. |
+| **Slug** | A URL-safe string. | A part of a path, or an identifier. |
+| **Number** | A numeric value. | A price, a count, or a rating. |
+| **Boolean** | A true or false value. | A toggle or a flag. |
+| **Date** | A date value. | A publish date or a deadline. |
+| **Color** | A color value. | A theme accent or a swatch. |
+| **JSON** | Any JSON value. | Structured data with no editor of its own. |
+| **Group** | An object of fields inside the layout. | A set of related fields, held together. |
+| **Section** | A [Section](/content/sections) schema inside the layout. | A shared schema fragment that you reuse. |
+| **Asset** | A link to an [Asset Library](/content/asset-library) item. | An image, a video, or a document. |
+| **HTML asset** | A link to a `.html` file in your library. | HTML that you wrote before, held inside the content. |
 
 ## Repeatable and grouped fields
 
-Any field can be made **repeatable**, which renders as a sortable list of values rather than a single value. Use it for galleries, feature lists, or any collection.
+You can make any field **repeatable**. It then renders as a sortable list of values,
+and not as one value. Use it for a gallery, for a list of features, or for any
+collection.
 
-A **Group** field nests a set of fields under one key, producing a structured object. Combine repeatable with a group to model a list of objects, such as a list of feature cards.
+A **Group** field holds a set of fields under one key, and it gives a structured
+object. Make a group repeatable to describe a list of objects, such as a list of
+feature cards.
 
-## Composing with sections
+## Build with sections
 
-A **Section** field embeds a reusable [Section](/content/sections) schema inside the layout. Define a common structure, such as a hero or a feature list, once as a Section, then reference it from any Page or Step Layout.
+A **Section** field holds a reusable [Section](/content/sections) schema inside the
+layout. Define a common structure one time as a Section, such as a hero or a list of
+features. Then point at it from any Page Layout or Step Layout.
 
-## Changing a schema
+## Change a schema
 
-Editing a layout's schema can leave existing Content Entries out of date. After a schema change, revalidate the entries that use the layout and fix any per-field errors before publishing.
+A change to the schema of a layout can make a Content Entry invalid. After such
+a change, check each entry that uses the layout again. Fix every field error before
+you publish.

package/dist/docs/content/pages.mdx

@@ -13,16 +13,19 @@ A Page is a standalone, server-rendered experience backed by CMS content, built
   alt="The experiences list, where Pages and Flows are created on the Picked dashboard"
 />
 
-## Pages vs flows
+## Pages and flows
 
-Picked has two kinds of experience:
+Picked has two experience kinds:
 
 | Experience | What it is | Use it for |
 | --- | --- | --- |
-| **Page** | A standalone experience rendered on your server, backed by a Content Entry. | SEO-critical landing pages, campaign pages, content the crawler must see. |
-| **Flow** | A multi-step, interactive experience rendered in the browser. | Quizzes, surveys, product finders, multi-step onboarding. |
+| **Page** | A standalone experience that your server renders from a Content Entry. | A landing page or a campaign page where the search rank matters, and any content that a crawler must see. |
+| **Flow** | An interactive experience of more than one step, which the browser renders. | A quiz, a survey, a product finder, and onboarding of more than one step. |
 
-Reach for a **Page** when the content must appear in the server HTML for search engines and social unfurls. Reach for a **Flow** when the value is in the interaction, and client-side rendering is fine. See [Experiences](/experiences) for the wider model.
+Choose a **Page** when the content must be in the HTML from your server, for a search
+engine and for a social preview. Choose a **Flow** when the value is in the
+interaction, and a browser render is acceptable. See
+[Experiences](/experiences) for the wider picture.
 
 ## How a page fits together
 
@@ -42,26 +45,38 @@ Author (dashboard) -> Publish -> Delivery API (config + content)
 
 ## Create a page
 
-1. Open your project and select a workspace.
-2. Click **Experiences** in the sidebar.
-3. Click **New Experience** and choose the **Page** type.
-4. Pick a **Page Layout**. The layout determines which fields the page holds.
-5. Click **Create**.
+1. Open your project.
+2. Choose a workspace.
+3. Click **Experiences** in the sidebar.
+4. Click **New Experience**.
+5. Choose the **Page** type.
+6. Choose a **Page Layout**. The layout sets which fields the page holds.
+7. Click **Create**.
 
 A Content Entry is created and linked to the page on its first save, so the page always has somewhere to store its data.
 
 ## Edit page content
 
-The Page editor has a **Properties** tab for the page's content and a **Settings** tab for its name, condition, and layout. Fill in the fields on the **Properties** tab. The inspector on the right edits the selected field, and the preview panel shows the page as it fills in.
+The Page editor has two tabs. The **Properties** tab holds the content of the page.
+The **Settings** tab holds its name, its condition, and its layout. Fill in the
+fields on the **Properties** tab. The inspector on the right edits the field that you
+choose, and the preview panel shows the page while it fills in.
 
 ## Change or remove the layout
 
-Use the change-layout control on the **Settings** tab to switch the page to a different Page Layout. Unlinking a layout detaches the Content Entry from the page. The entry is not deleted, but the page no longer has content to render until you bind a layout again.
+Use the change-layout control on the **Settings** tab to move the page to another
+Page Layout. When you unlink a layout, Picked separates the Content Entry from the
+page. It deletes no entry, but the page then has no content to render until you
+attach a layout again.
 
 ## Validate and publish
 
-Invalid fields surface inline as per-field errors while you edit, so you can fix them before publishing. When the page is valid, publish the workspace to make it live. Publishing produces the version the Delivery API serves to anonymous readers.
+An invalid field shows an error next to it while you edit, so that you can correct it
+before you publish. When the page is valid, publish the workspace to make it live.
+That makes the version that the Delivery API serves to an anonymous reader.
 
 ## Render a page
 
-A published Page is rendered by the SDK on your server. See the [Build a Personalized Page](/guides/build-a-personalized-page) guide for the end-to-end walkthrough, and [Server-Side Rendering](/sdk/ssr) for the SDK reference.
+The SDK renders a published Page on your server. See the
+[Build a Personalized Page](/guides/build-a-personalized-page) guide for the full
+steps, and [Server-Side Rendering](/sdk/ssr) for the SDK reference.