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

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.

package/dist/docs/flow-builder/building-flows.md

@@ -2,60 +2,78 @@
 layout: docs
 ---
 
-# Building flows
+# Build flows
 
-Build flows by dragging blocks onto the canvas, connecting nodes with arrows, and configuring each node in the inspector.
+To build a flow, drag a block onto the canvas. Connect your nodes with arrows. Then
+set the options of each node in the inspector.
 
 ## Add nodes
 
-Drag a step, action, or condition from the entity browser onto the canvas. A new node appears where you drop it.
+Drag a step, an action, or a condition from the entity browser onto the canvas. A new
+node appears where you drop it.
 
-You can also drop a block directly onto an existing arrow. The node inserts inline — the original arrow splits into two arrows with the new node in between. A **+** indicator appears when you hover over a valid arrow.
+You can also drop a block directly onto an arrow that is there already. The flow
+builder puts the node into the line. The first arrow splits into two arrows, with the
+new node between them. A **+** indicator appears when you hold the pointer over a
+valid arrow.
 
 ## Connect nodes
 
-Click and drag from a node's output handle (right side) to another node's input handle (left side). An arrow appears connecting them.
+Click the output handle of a node, on the right side. Drag to the input handle of
+another node, on the left side. An arrow then joins the two nodes.
 
-The flow follows arrows from left to right, starting at the origin. Every node downstream of the origin is part of the experience flow.
+The flow follows the arrows from left to right, and it starts at the origin. Every
+node after the origin is part of the experience flow.
 
 ## Branch with conditions
 
-Connect the origin (or any node) to a condition node. The condition evaluates its logic and routes the flow down one of two paths.
+Connect the origin, or any other node, to a condition node. The condition evaluates
+its rule and sends the flow down one of two paths.
 
-Connect the green (true) handle to the nodes that should run when the condition passes. Connect the red (false) handle to the alternative path. Either path can lead to more steps, actions, or further conditions.
+Connect the green handle, for a true result, to the nodes that must run when the
+condition holds. Connect the red handle, for a false result, to the other path. Each
+path can lead to more steps, more actions, and more conditions.
 
 ## Assign fields to steps
 
-Drag a field from the entity browser and drop it onto a step node. The field is now assigned to that step.
+Drag a field from the entity browser onto a step node and drop it. That step then
+holds the field.
 
-You can assign multiple fields to a single step. The step node shows a count of assigned fields. To see which fields are assigned, select the step and check the **Assigned Fields** section in the inspector.
+You can assign more than one field to one step. The step node gives the number of
+assigned fields. To see which fields it holds, choose the step. Then read the
+**Assigned Fields** section in the inspector.
 
-## Select nodes
+## Choose nodes
 
-Click a node to select it. Its inspector opens in the right panel.
+Click a node to choose it. Its inspector opens in the right panel.
 
-Drag on empty canvas to marquee-select multiple nodes. Press `Cmd/Ctrl+A` to select all nodes.
+Drag on empty canvas to choose every node inside a rectangle. Press `Cmd/Ctrl+A` to
+choose every node.
 
-When multiple nodes are selected, the inspector shows a count and grouped list. Click any item in the list to navigate to its inspector.
+When you choose more than one node, the inspector gives a count and a list in groups.
+Click an item in that list to open its inspector.
 
 ## Move nodes
 
-Drag a selected node to reposition it. Nodes snap to the grid automatically.
+Drag a node to move it. Each node snaps to the grid.
 
-Use arrow keys to nudge selected nodes. Hold `Shift` for larger nudges.
+Use the arrow keys to move a node a small distance. Hold `Shift` to move it further.
 
 ## Delete nodes
 
-Select one or more nodes and press `Delete` or `Backspace`. The nodes and their connected arrows are removed.
+Choose one or more nodes. Press `Delete` or `Backspace`. The flow builder removes
+those nodes and every arrow that joins them.
 
 ## Duplicate nodes
 
-Select one or more nodes and press `Cmd/Ctrl+D`. Copies appear offset from the originals.
+Choose one or more nodes. Press `Cmd/Ctrl+D`. A copy of each node appears next to the
+first one.
 
 ## Undo and redo
 
-Press `Cmd/Ctrl+Z` to undo. Press `Cmd/Ctrl+Shift+Z` to redo. The undo stack tracks node additions, deletions, connections, and position changes.
+Press `Cmd/Ctrl+Z` to undo. Press `Cmd/Ctrl+Shift+Z` to redo. The undo stack records
+each node that you add, each node that you delete, each connection, and each move.
 
 ---
 
-[Overview](/flow-builder/overview) · [Nodes](/flow-builder/nodes) · **Building Flows** · [Keyboard Shortcuts](/flow-builder/keyboard-shortcuts) · [Condition Builder](/flow-builder/condition-builder)
+[Overview](/flow-builder/overview) · [Nodes](/flow-builder/nodes) · **Build Flows** · [Keyboard Shortcuts](/flow-builder/keyboard-shortcuts) · [Condition Builder](/flow-builder/condition-builder)

package/dist/docs/flow-builder/condition-builder.md

@@ -4,51 +4,62 @@ layout: docs
 
 # Condition builder
 
-The condition builder is a visual rule editor used across the dashboard. It lets you define logic without writing code.
+The condition builder is a visual rule editor, and the dashboard uses it in several
+places. With it you define a rule and you write no code.
 
 ## Where it appears
 
-The condition builder is used in several places:
+The dashboard uses the condition builder here:
 
-- **Condition nodes** — define branching logic in the [flow builder](/flow-builder/overview)
-- **Experience conditions** — control when an experience activates for a visitor
-- **Initialize open conditions** — control when an experience opens automatically on page load
-- **Field option conditions** — show or hide individual options based on visitor state
+- **Condition nodes** — they set which branch the flow takes in the
+  [flow builder](/flow-builder/overview).
+- **Experience conditions** — they control when an experience starts for a visitor.
+- **Initialize open conditions** — they control when an experience opens by itself as
+  the page loads.
+- **Field option conditions** — they show or hide one option, and the state of the
+  visitor decides which.
 
 ## Rule structure
 
-Rules are organized into groups. Each group uses either **AND** (all rules must match) or **OR** (any rule must match).
+The builder holds your rules in groups. Each group uses **AND** or **OR**. With
+**AND**, every rule must match. With **OR**, one rule must match.
 
 A single rule has three parts:
 
-1. **Field** — the data source to evaluate
-2. **Operator** — how to compare (equals, not equals, greater than, contains, etc.)
-3. **Value** — the target value to compare against
+1. **Field** — the data source to evaluate.
+2. **Operator** — how to compare. Examples are equals, not equals, greater than, and
+   contains.
+3. **Value** — the value to compare against.
 
-You can nest groups inside other groups to create complex logic. For example, an AND group containing two OR groups.
+You can put a group inside another group to build a larger rule. An example is an AND
+group that holds two OR groups.
 
-## Available data sources
+## Data sources
 
-When building rules, you can reference these data sources:
+A rule can point at these data sources:
 
-**Responses** — values visitors have submitted through form fields in the current experience. Each field you create in your project appears here by its name.
+**Responses** — the values that your visitors send through the form fields of the
+current experience. Each field that you create in your project appears here under its
+name.
 
-**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. Use this to branch on whether a visitor is allocated to a flag.
+**Feature flags** — the state of each feature flag in your project. Use it to take a
+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.
+**Location** — the parts of the current page URL of the visitor. These are the
+pathname, the search parameters, the hostname, and the hash.
 
 ## Example
 
-To show a step only to visitors on a specific page who opted into marketing:
+To show a step only to a visitor who is on one page and who accepted marketing:
 
 1. Create an AND group.
 2. Add a rule: **Location → pathname** equals `/pricing`.
-3. Add a rule: **Responses → marketing_opt_in** equals `true`.
+3. Add a rule: **Responses → `marketing_opt_in`** equals `true`.
 
-Both conditions must be true for the rule group to match.
+The rule group matches only when both conditions are true.
 
 ---
 
-[Overview](/flow-builder/overview) · [Nodes](/flow-builder/nodes) · [Building Flows](/flow-builder/building-flows) · [Keyboard Shortcuts](/flow-builder/keyboard-shortcuts) · **Condition Builder**
+[Overview](/flow-builder/overview) · [Nodes](/flow-builder/nodes) · [Build Flows](/flow-builder/building-flows) · [Keyboard Shortcuts](/flow-builder/keyboard-shortcuts) · **Condition Builder**