@picked/client 0.0.70-next.6 → 0.0.70

package/dist/docs/content/sections.mdx

@@ -15,19 +15,30 @@ Sections are reusable schema fragments you embed inside layouts, so common struc
 
 ## What a section is
 
-A Section is a reusable fragment of schema with its own **Key**. Where a [layout](/content/layouts) backs a whole Page or Step, a Section is a piece you compose into one or more layouts. Define the shape once, reuse it everywhere.
+A Section is a reusable schema fragment with its own **Key**. A
+[layout](/content/layouts) gives its shape to a whole Page or Step. A Section is a
+part that you put into one or more layouts. Define the shape one time, then reuse it
+everywhere.
 
 ## Create a section
 
-1. Open your workspace and click **Sections** in the sidebar.
-2. Click **New Section**.
-3. Enter a name and a **Key**. The Key is a unique, stable identifier used in SDK code and API references.
-4. Add fields and save.
+1. Open your workspace.
+2. Click **Sections** in the sidebar.
+3. Click **New Section**.
+4. Enter a name and a **Key**. The Key is a unique, stable identifier. Your SDK code
+   and your API calls both use it.
+5. Add your fields.
+6. Save.
 
 ## Use a section in a layout
 
-Add a **Section** field to a Page or Step Layout and point it at the Section you want to embed. The layout then carries the Section's fields wherever that field appears. A Content Entry built from the layout fills the Section's fields like any others.
+Add a **Section** field to a Page Layout or a Step Layout. Point that field at the
+Section that you want. The layout then carries the fields of the Section at every
+place where that field appears. A Content Entry from the layout fills in the fields
+of the Section in the same way as every other field.
 
-## Changing a section
+## Change a section
 
-Editing a Section does not automatically migrate the entries that already use it. After changing a Section, revalidate the affected [Content Entries](/content/content-entries) and resolve any per-field errors before publishing.
+An edit to a Section does not migrate the entries that use it. After you change a
+Section, check each affected [Content Entry](/content/content-entries) again. Correct
+every field error before you publish.

package/dist/docs/delivery-api/experience-content.md

@@ -16,7 +16,7 @@ GET /api/v1/projects/:projectId/experiences/:id/content
 | --- | --- | --- |
 | `projectId` | path | The project the experience belongs to. |
 | `id` | path | The experience to fetch content for. |
-| `preview_token` | query | Optional. Returns preview (unpublished) content when present. |
+| `preview_token` | query | Optional. With it, the endpoint returns preview content, which is unpublished. |
 
 ## Response
 
@@ -40,11 +40,14 @@ GET /api/v1/projects/:projectId/experiences/:id/content
 | `versionId` | `string \| null` | The published version id, or `null` on preview. |
 | `content[].id` | `string` | The Content Entry id. |
 | `content[].contentModelKey` | `string \| null` | The layout's Key, or `null` when it cannot be resolved. |
-| `content[].data` | `object` | The entry data, matching the layout schema. |
+| `content[].data` | `object` | The entry data. It matches the layout schema. |
 
-## HTML asset inlining
+## An HTML asset comes back in the response
 
-When the layout has an [HTML asset](/content/asset-library) field, its value arrives inlined. The reference is rewritten to `{ id, content }`, where `content` is the uploaded HTML as a string (or `null` when it cannot be resolved):
+A layout can have an [HTML asset](/content/asset-library) field. The value of that
+field arrives inside the response. The endpoint changes the reference to
+`{ id, content }`. There, `content` holds the HTML that you uploaded, as a string. It
+is `null` when the endpoint cannot resolve it:
 
 ```json
 {
@@ -82,4 +85,6 @@ curl https://api.picked.app/api/v1/projects/proj_123/experiences/exp_123/content
 }
 ```
 
-See [Project Config](/delivery-api/project-config) for the endpoint that links steps to entries, [Asset Library](/content/asset-library) for HTML assets, and [Server Snapshot](/sdk/ssr/serialize) for how the SDK consumes this content.
+See [Project Config](/delivery-api/project-config) for the endpoint that links a step
+to an entry. See [Asset Library](/content/asset-library) for an HTML asset. See
+[Server Snapshot](/sdk/ssr/serialize) for how the SDK reads this content.

package/dist/docs/delivery-api/index.md

@@ -4,20 +4,23 @@ layout: docs
 
 # Delivery API
 
-The Delivery API is a public, read-only REST API that serves your published project config and page content. It is separate from the GraphQL management API.
+The Delivery API is a public REST API. It is read-only, and it serves the published
+options of your project together with your page content. It is separate from the
+GraphQL management API.
 
-## Delivery API vs the management API
+## The Delivery API and the management API
 
-Picked has two HTTP APIs. Use the one that fits the job:
+Picked has two HTTP APIs. Use the one that fits your work:
 
 | | Delivery API | Management API |
 | --- | --- | --- |
 | Style | REST | GraphQL |
 | Access | Public, anonymous | Authenticated |
 | Operations | Read-only | Read and write |
-| Use for | Serving published config and content to your app | Managing projects, experiences, and content |
+| Use it to | Serve published options and content to your application | Control your projects, experiences, and content |
 
-The management API is documented under [API Reference](/api). This section covers the Delivery API.
+The [API Reference](/api) covers the management API. This section covers the Delivery
+API.
 
 ## Base URL and versioning
 
@@ -27,20 +30,24 @@ All Delivery API routes are versioned under `/api/v1`:
 https://api.picked.app/api/v1
 ```
 
-## Published vs preview
+## Published content and preview content
 
 Each endpoint serves two surfaces:
 
-- **Published** content is anonymous. Anyone can read your published config and content.
-- **Preview** content is gated by a `preview_token` query parameter, so you can render unpublished drafts before going live.
+- **Published** content is anonymous. Anybody can read your published options and
+  your published content.
+- **Preview** content needs a `preview_token` query parameter. With it you can render
+  an unpublished draft before you make it live.
 
-A workspace's preview token is available as the `previewToken` field on the workspace in the management API, and the dashboard preview action issues one for you.
+The management API holds the preview token of a workspace in the `previewToken`
+field. The preview action in the dashboard also makes one for you.
 
 ## Endpoints
 
 | Endpoint | Description |
 | --- | --- |
-| [Project Config](/delivery-api/project-config) | `GET /api/v1/projects/:projectId` returns the published project config, including each step's content link. |
-| [Experience Content](/delivery-api/experience-content) | `GET /api/v1/projects/:projectId/experiences/:id/content` returns the Content Entries that back an experience. |
+| [Project Config](/delivery-api/project-config) | `GET /api/v1/projects/:projectId` returns the published options of the project, with the content link of each step. |
+| [Experience Content](/delivery-api/experience-content) | `GET /api/v1/projects/:projectId/experiences/:id/content` returns the Content Entries of an experience. |
 
-For the operational details shared by both endpoints, see [Preview, Caching & Crawling](/delivery-api/preview-caching-crawling).
+Both endpoints share some behaviour. See
+[Preview, cache, and crawlers](/delivery-api/preview-caching-crawling).

package/dist/docs/delivery-api/preview-caching-crawling.md

@@ -2,23 +2,30 @@
 layout: docs
 ---
 
-# Preview, Caching & Crawling
+# Preview, cache, and crawlers
 
-The operational surface shared by both Delivery API endpoints: preview tokens, caching, CORS, and crawling.
+Both Delivery API endpoints share this behaviour: the preview token, the cache, CORS,
+and what a crawler can read.
 
 ## Preview tokens
 
-Pass `?preview_token=<token>` to read unpublished content. Both endpoints accept it, and both return `versionId: null` on the preview surface. An invalid token returns `401`.
+Pass `?preview_token=<token>` to read unpublished content. Both endpoints take it,
+and both return `versionId: null` for a preview. An invalid token returns `401`.
 
 ```bash
 curl "https://api.picked.app/api/v1/projects/proj_123?preview_token=<token>"
 ```
 
-A workspace's preview token is available as the `previewToken` field on the workspace in the [management API](/api), and the dashboard preview action issues one for you. Use the same token for the project config and the experience content requests so both come from the same preview surface.
+The [management API](/api) holds the preview token of a workspace in the
+`previewToken` field. The preview action in the dashboard also makes one for you.
 
-## Caching
+Use the same token for the project options request and for the experience content
+request. Both then come from the same preview.
 
-Caching depends on the surface and the requesting client. The SDK sends a `Picked-Client: sdk` request header:
+## Cache
+
+The cache rules depend on the surface and on the client that makes the request. The
+SDK sends a `Picked-Client: sdk` request header:
 
 | Request | `Cache-Control` |
 | --- | --- |
@@ -26,11 +33,14 @@ Caching depends on the surface and the requesting client. The SDK sends a `Picke
 | Published, other clients | `private, no-store` |
 | Preview | `no-store` |
 
-Cacheable published responses also send `Vary: Picked-Client`, so a shared cache keys on the client header and never serves an SDK-cached body to a non-SDK request.
+A published response that a cache can hold also sends `Vary: Picked-Client`. A shared
+cache therefore keys on the client header. It never gives a body that it cached for
+the SDK to a request from another client.
 
 ## CORS
 
-Both endpoints are cross-origin readable. An `OPTIONS` preflight returns `204` with the CORS headers:
+Both endpoints can be read from another origin. An `OPTIONS` preflight returns `204`
+with the CORS headers:
 
 | Header | Value |
 | --- | --- |
@@ -38,22 +48,25 @@ Both endpoints are cross-origin readable. An `OPTIONS` preflight returns `204` w
 | `Access-Control-Allow-Methods` | `GET, OPTIONS` |
 | `Access-Control-Allow-Headers` | `Content-Type, Picked-Client, Picked-Version, traceparent, tracestate` |
 
-## Crawling and SEO
+## Crawlers and search rank
 
-Both endpoints are crawlable so search engines can read your published content. Preview URLs are disallowed, so drafts never reach the index. The `robots.txt` rules:
+A crawler can read both endpoints, so a search engine can read your published
+content. A preview URL is disallowed, so a draft never reaches the index. These are
+the `robots.txt` rules:
 
 ```
 User-agent: *
 
-# Allow crawling of the public project config and experience content endpoints
+# Let a crawler read the public project options and experience content.
 Allow: /api/v1/projects
 Allow: /api/v1/projects/*/experiences/*/content
 
-# Keep preview (draft) responses out of crawlers
+# Keep a preview response, which is a draft, away from a crawler.
 Disallow: /api/v1/projects/*preview_token=
 
-# Everything else (GraphQL, MCP, internal, ping) stays disallowed
+# Everything else stays disallowed: GraphQL, MCP, internal routes, and the ping.
 Disallow: /
 ```
 
-See [Project Config](/delivery-api/project-config) and [Experience Content](/delivery-api/experience-content) for the endpoints themselves.
+See [Project Config](/delivery-api/project-config) and
+[Experience Content](/delivery-api/experience-content) for the endpoints.

package/dist/docs/delivery-api/project-config.md

@@ -15,7 +15,7 @@ GET /api/v1/projects/:projectId
 | Parameter | In | Description |
 | --- | --- | --- |
 | `projectId` | path | The project to fetch config for. |
-| `preview_token` | query | Optional. Returns the preview (unpublished) config when present. |
+| `preview_token` | query | Optional. With it, the endpoint returns the preview options, which are unpublished. |
 
 ## Response
 
@@ -25,11 +25,13 @@ The response carries the project's experiences and steps. Each step includes `la
 | --- | --- | --- |
 | `id` | `string` | The project id. |
 | `versionId` | `string \| null` | The published version id, or `null` on preview. |
-| `steps[].layoutContentId` | `string \| null` | The Content Entry backing this step, or `null` when the step has no content. |
+| `steps[].layoutContentId` | `string \| null` | The Content Entry of this step, or `null` when the step has no content. |
 
-## Published vs preview
+## Published content and preview content
 
-On the published surface, `versionId` is the published version id. On the preview surface (`?preview_token=...`), `versionId` is `null` because there is no published version. See [Preview, Caching & Crawling](/delivery-api/preview-caching-crawling).
+For published content, `versionId` holds the ID of the published version. For preview
+content, which you read with `?preview_token=...`, `versionId` is `null`, because
+there is no published version. See [Preview, cache, and crawlers](/delivery-api/preview-caching-crawling).
 
 ## Example
 

package/dist/docs/experiences.mdx

@@ -6,9 +6,14 @@ import { Screenshot } from '../../components/Screenshot'
 
 # Experiences
 
-An experience is a personalized experience delivered to visitors on your site. Each experience maps to a component registered in your application.
+An experience is personalized content that Picked serves to the visitors on your
+site. Each experience points at a component that you register in your application.
 
-Picked has two kinds of experience. A **Flow** is a multi-step, interactive experience rendered in the browser, covered on this page. A **Page** is a standalone, server-rendered experience backed by CMS content, built for SEO-critical landing pages. See [Pages](/content/pages) for that kind.
+An experience is either a **Flow** or a **Page**. A **Flow** is an interactive
+experience of more than one step, and the browser renders it. This page covers the
+flow. A **Page** is a standalone experience that the server renders from CMS content,
+for a landing page where the search rank matters. See [Pages](/content/pages) for
+that kind.
 
 <Screenshot
   route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/experiences"
@@ -20,23 +25,34 @@ Picked has two kinds of experience. A **Flow** is a multi-step, interactive expe
 1. Open your project.
 2. Click **Experiences** in the sidebar.
 3. Click **New Experience**.
-4. Enter a name and a component name. The component name must match a component registered in your application. See [SDK Experiences](/sdk/experiences) for details on registering components.
+4. Enter a name and a component name. The component name must match a component that
+   you register in your application. See [SDK Experiences](/sdk/experiences) for how
+   to register a component.
 5. Click **Create**.
 
-The flow editor opens with an empty canvas. See [Building Flows](/flow-builder/building-flows) to start adding nodes.
+The flow editor opens with an empty canvas. See
+[Build Flows](/flow-builder/building-flows) to add your first node.
 
 ## Experience settings
 
-Select no nodes on the canvas (or click the canvas background) to open the experience inspector in the right panel.
+Choose no node on the canvas, or click the canvas background, to open the experience
+inspector in the right panel.
 
-**Name**: The display name shown in the dashboard. Visitors don't see this.
+**Name**: The name that the dashboard shows. Your visitors do not see it.
 
-**Component Name**: The identifier that maps this experience to a registered component in your application.
+**Component Name**: The identifier that points this experience at a component in your
+application.
 
-**Condition**: An optional activation condition. When set, the experience only activates for visitors who match the condition logic. See [Condition Builder](/flow-builder/condition-builder) for details on configuring conditions. Leave blank to activate for all visitors.
+**Condition**: An optional condition. When you set it, the experience starts only for
+a visitor who matches the condition. See
+[Condition Builder](/flow-builder/condition-builder) for how to write one. Keep it
+blank to start the experience for every visitor.
 
-**Initialize Open**: An optional condition that controls whether the experience opens automatically on page load. When blank, the experience loads but stays closed until opened.
+**Initialize Open**: An optional condition that controls whether the experience opens
+by itself when the page loads. When it is blank, the experience loads but stays
+closed until something opens it.
 
 ## Experience list
 
-The experiences list shows all experiences in the current project. Click any experience to open it in the flow builder.
+The experiences list shows every experience in the current project. Click an
+experience to open it in the flow builder.

package/dist/docs/features.mdx

@@ -6,7 +6,8 @@ import { Screenshot } from '../../components/Screenshot'
 
 # Feature flags
 
-Feature flags let you run A/B tests and roll changes out gradually. Control which visitors see a change to your site, without deploying code.
+A feature flag lets you run an A/B test and roll a change out in stages. It controls
+which visitors see a change to your site, and you deploy no code.
 
 <Screenshot
   route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/features"
@@ -23,66 +24,106 @@ Feature flags let you run A/B tests and roll changes out gradually. Control whic
 
 ## Keys
 
-Each feature flag has a unique key. Use this key in your application to check whether a visitor is allocated to the feature flag. The key is set when you create the feature flag and cannot be changed later.
+Each feature flag has a unique key. Your application uses this key to check whether
+Picked allocates a visitor to the feature flag. You set the key when you create the
+feature flag, and you cannot change it later.
 
 ## Configure allocation
 
-Set allocation from the feature flag detail page:
+Set the allocation from the detail page of the feature flag:
 
 | Control | What it does |
 | --- | --- |
-| **Enabled** | Whether visitors are allocated to the feature flag. A disabled feature flag allocates nobody, and records nothing — see [Disabling a feature flag](#disabling-a-feature-flag). |
-| **Weight** | The percentage of visitors allocated to the feature flag, from 0 to 100. |
-| **Description** | An internal note describing what the feature flag tests. |
+| **Enabled** | Whether Picked allocates a visitor to the feature flag. A feature flag that is off allocates nobody, and it records nothing. See [Turn a feature flag off](#turn-a-feature-flag-off). |
+| **Weight** | The percentage of visitors that Picked allocates to the feature flag, from 0 to 100. |
+| **Description** | An internal note about what the feature flag tests. |
 
-A feature flag has one weight, and resolves to one of two outcomes per visitor: allocated, or not. A weight of 30 allocates 30% of visitors and leaves the other 70% unallocated. A weight of 0 allocates nobody; a weight of 100 allocates everybody.
+A feature flag has one weight. For each visitor it gives one of two outcomes:
+allocated, or not allocated. A weight of 30 allocates 30% of your visitors. The other
+70% stay unallocated. A weight of 0 allocates nobody. A weight of 100 allocates
+everybody.
 
 ## How visitors are allocated
 
-Allocation is deterministic. Each visitor is assigned a stable value derived from their visitor ID and the feature flag, which is compared against the feature flag's weight — if the value falls below the weight, the visitor is allocated.
+The allocation is deterministic. Picked gives each visitor a stable value for each
+feature flag. It derives that value from the visitor ID and from the ID of the feature
+flag. It then compares the value against the weight. When the value is below the
+weight, Picked allocates the visitor.
 
-The same visitor always gets the same result for a given feature flag, on every visit, as long as the weight stays the same. The version is not part of that value — it controls caching only, covered under [Feature flag versions](#feature-flag-versions).
+The same visitor always gets the same result for one feature flag, on every visit,
+while the weight stays the same. The version is not part of that value. It controls
+the cache only. See [Feature flag versions](#feature-flag-versions).
 
-Each feature flag draws its own value, so concurrent tests are independent of one another. Two feature flags both at weight 50 split visitors into four equal quarters — allocated to both, to one, to the other, to neither. Three feature flags at weight 50 give eight groups of 12.5%, and so on for each feature flag you add.
+Each feature flag gets its own value, so tests that run at the same time are
+independent. Two feature flags, both at weight 50, split your visitors into four equal
+parts: allocated to both, to one, to the other, or to neither. Three feature flags at
+weight 50 give eight groups of 12.5%.
 
 :::note
-Within a single feature flag, raising the weight only ever adds visitors. Everyone allocated at weight 30 is still allocated at weight 50, so you can ramp a rollout up without moving anyone already in it. Lowering the weight removes visitors from the top of the range.
+Inside one feature flag, a larger weight only adds visitors. Everybody at weight 30 is
+still allocated at weight 50, so you can make a release wider and move nobody who is
+in it already. A smaller weight removes visitors from the top of the range.
 :::
 
-## Disabling a feature flag
+## Turn a feature flag off
 
-A disabled feature flag allocates nobody, and the distinction from a weight of 0 matters for your reporting: a visitor is **not in the test at all**, rather than assigned to control.
+A feature flag that is off allocates nobody, and it records nothing. The difference
+from a weight of 0 matters for your reports. The visitor is **not in the test at
+all**, and the visitor is not in the control group.
 
-Nothing is recorded. The SDK does not evaluate the feature flag, stores no decision in the visitor's browser, and reports no decision to analytics. Disabled feature flags are absent from the feature list on every analytics event.
+The SDK does not evaluate a feature flag that is off. It stores no decision in the
+browser of the visitor, and it reports no decision to your analytics. Such a feature
+flag is absent from the feature list on every analytics event.
 
-Experiences whose conditions reference a disabled feature flag behave as though the visitor is not in the test — the condition reads as not allocated, without an assignment being recorded.
+An experience whose condition points at a feature flag that is off behaves as though
+the visitor is not in the test. The condition reads as not allocated, and Picked
+records no assignment.
 
-Disabling is temporary and does not discard decisions already made. A visitor who was allocated before you disabled the feature flag keeps that decision in their browser, and re-enabling picks up where it left off rather than re-drawing them.
+This state is temporary, and it discards no decision that Picked made already. A
+visitor who was allocated before keeps that decision in the browser. When you turn the
+feature flag on again, Picked continues from that decision and does not allocate the
+visitor again.
 
 :::note
-Expect a step change in reporting when a feature flag is disabled: fewer feature flags per visitor, and fewer decision events overall. That is the disabled feature flag dropping out, not data loss.
+Expect a step change in your reports when you turn a feature flag off: fewer feature
+flags for each visitor, and fewer decision events. That is the feature flag that drops
+out, and you lose no data.
 :::
 
-Disabled feature flags remain visible in developer tooling, and a [URL override](/sdk/features#url-based-overrides) still forces one on for QA.
+A feature flag that is off stays visible in the developer tools, and a
+[URL override](/sdk/features#overrides-in-the-url) still turns one on for QA.
 
 ## Feature flag versions
 
-Each feature flag has a version number, starting at 1. The version forms part of the key the SDK uses to cache allocation decisions in the visitor's browser, and nothing else — it is not an input to the allocation value itself. Incrementing it discards those cached decisions, so every visitor is evaluated again on their next page load.
+Each feature flag has a version number, and it starts at 1. The SDK caches an
+allocation decision in the browser of the visitor under a key, and the version is part
+of that key. The version does nothing else, and it is not an input to the allocation
+value. When you increment the version, the SDK discards those cached decisions. It
+then evaluates every visitor again on the next page load.
 
 ### What happens when you increment the version
 
-- **Cached decisions are invalidated.** The SDK caches decisions under a key that includes the version, so the old entry no longer matches and the feature flag is treated as undecided.
-- **Visitors are re-evaluated against the current weight.** Allocation is deterministic and the version is not one of its inputs, so re-evaluating the same visitor against an unchanged weight produces the same result.
-- **This is irreversible.** You cannot decrement a version.
+- **The SDK invalidates the cached decisions.** The cache key holds the version, so the
+  old entry no longer matches and the feature flag counts as undecided.
+- **Picked evaluates each visitor against the current weight.** The allocation is
+  deterministic and the version is not one of its inputs, so the same visitor against
+  an unchanged weight gives the same result.
+- **You cannot reverse this.** There is no way to decrement a version.
 
 :::note
-Incrementing the version does not reshuffle visitors. It clears cached decisions and runs allocation again — with an unchanged weight, everyone lands where they were. Change the weight if you want visitors to move.
+The new version does not move your visitors between groups. It clears the cached
+decisions and runs the allocation again. With an unchanged weight, everybody lands
+where they were before. Change the weight to move your visitors.
 :::
 
 ### When to increment
 
-Increment the version after changing the weight, when you want visitors who are already allocated to be re-evaluated against the new weight rather than keeping their cached decision.
+Increment the version after you change the weight. Do this when you want Picked to
+evaluate an allocated visitor again against the new weight, and not to use the cached
+decision.
 
 ### When not to increment
 
-If you want a weight change to affect only visitors who have not been allocated yet, change the weight without incrementing the version. Existing visitors keep their current allocation.
+To apply a weight change only to a visitor that Picked does not allocate yet, change
+the weight and leave the version as it is. An allocated visitor keeps the current
+allocation.

package/dist/docs/fields.mdx

@@ -6,9 +6,12 @@ import { Screenshot } from '../../components/Screenshot'
 
 # Fields
 
-A field is a data input shown to visitors inside a step. Fields collect information like names, email addresses, preferences, or selections.
+A field is a data input that a visitor sees inside a step. A field collects
+information such as a name, an email address, a preference, or a choice.
 
-These are experience Fields, which collect visitor input. They are distinct from the Content Fields that make up a CMS layout's schema, covered in [Page & Step Layouts](/content/layouts).
+This page covers the experience field, which collects visitor input. An experience
+field is not the same as a content field. A content field is part of the schema of a
+CMS layout. See [Page and Step Layouts](/content/layouts) for those.
 
 <Screenshot
   route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/fields"
@@ -20,60 +23,72 @@ These are experience Fields, which collect visitor input. They are distinct from
 1. Open your project.
 2. Click **Fields** in the sidebar.
 3. Click **New Field**.
-4. Enter a name, key, and label.
-5. Select a type.
+4. Enter a name, a key, and a label.
+5. Choose a type.
 6. Click **Create**.
 
 ## Field types
 
-Fields support many types. Here are some common examples:
+A field has one of many types. These are the common ones:
 
-`TEXT`: A string input. Use for names, emails, free-form text.
+`TEXT`: A string input. Use it for a name, an email address, or free text.
 
-`NUMBER`: A numeric input. Use for quantities, ratings, ages.
+`NUMBER`: A numeric input. Use it for a quantity, a rating, or an age.
 
-`BOOLEAN`: A true/false toggle. Use for checkboxes, opt-ins, consent.
+`BOOLEAN`: A true or false toggle. Use it for a checkbox or for consent.
 
-`OBJECT`: A structured data input. Use for complex or nested data.
+`OBJECT`: A structured data input. Use it for data that holds other data.
 
-## Configuration
+## Options
 
-**Name**: Display name in the dashboard. Not visible to visitors.
+**Name**: The name that the dashboard shows. Your visitors do not see it.
 
-**Key**: 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.
 
-**Label**: The label visitors see next to the field.
+**Label**: The label that a visitor sees next to the field.
 
-**Placeholder**: Hint text shown inside the input when empty.
+**Placeholder**: The hint text that the input shows while it is empty.
 
-**Description**: A longer description of the field's purpose. Shown in the dashboard, not to visitors.
+**Description**: A longer description of what the field is for. The dashboard shows
+it. Your visitors do not see it.
 
-**Help Text**: Assistive text shown to visitors below the field.
+**Help Text**: Text below the field that helps your visitors.
 
-**Default Value**: The initial value when the field loads.
+**Default Value**: The value that the field holds when it loads.
 
 ## Validation
 
-**Required**: When enabled, visitors must fill in this field before proceeding.
+**Required**: When this is on, a visitor must fill in the field before the flow can
+continue.
 
-**Validation rules**: Define conditions for advanced constraints like minimum/maximum values, patterns, or custom logic. See [Condition Builder](/flow-builder/condition-builder) for details on building validation rules.
+**Validation rules**: Conditions for a constraint such as a smallest value, a largest
+value, or a pattern. See [Condition Builder](/flow-builder/condition-builder) for how
+to build a validation rule.
 
-## Multiple values
+## More than one value
 
-Enable **Multiple** to allow visitors to submit more than one value for this field. Useful for multi-select inputs or tag-style fields.
+Turn on **Multiple** to let a visitor send more than one value for the field. This is
+useful for an input that takes several choices, or for a field of tags.
 
-## Options
+## Choices
 
-For fields that present a fixed set of choices (like dropdowns or radio buttons), add options. Each option has a value that gets submitted with the response.
+For a field with a fixed set of choices, such as a dropdown or a set of radio
+buttons, add options. Each option has a value, and the response carries that value.
 
-Each option can also have a condition applied. When a condition is set, the option only appears to visitors who match the condition logic. See [Condition Builder](/flow-builder/condition-builder) for details.
+Each option can also carry a condition. When you set one, the option appears only to
+a visitor who matches the condition. See
+[Condition Builder](/flow-builder/condition-builder) for more detail.
 
 ## Privacy
 
-**Do Not Track**: When enabled, this field's data is excluded from analytics tracking.
+**Do Not Track**: When this is on, Picked keeps the data of this field out of your
+analytics.
 
-**Do Not Store**: When enabled, this field's data is processed but not persisted. Use for sensitive information like passwords or payment details.
+**Do Not Store**: When this is on, Picked reads the data of this field but does not
+keep it. Use it for sensitive information such as a password or payment detail.
 
 ## Reuse fields
 
-Fields are project-level entities. Assign the same field to multiple steps across different experiences. Changes to a field's configuration apply everywhere it's used.
+A field is a project-level entity. Assign the same field to steps in more than one
+experience. A change to the options of a field applies at every place that uses it.