@picked/client 0.0.1-dev.1785305085063 → 0.0.1-dev.1785826066660

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

@@ -4,55 +4,126 @@ layout: docs
 
 import { Screenshot } from '../../components/Screenshot'
 
-# Features
+# Feature flags
 
-Features let you run A/B tests and feature flags. Control which visitors see which variant of your site without deploying code changes.
+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"
-  alt="The features list for a workspace on the Picked dashboard"
+  alt="The feature flags list for a workspace on the Picked dashboard"
 />
 
-## Create a feature
+## Create a feature flag
 
 1. Open your project.
-2. Click **Features** in the sidebar.
-3. Click **New Feature**.
+2. Click **Feature flags** in the sidebar.
+3. Click **New feature flag**.
 4. Enter a name.
-5. Click **Create**.
+5. Click **Create feature flag**.
 
 ## Keys
 
-Each feature has a unique key. Use this key in your application to check which variant a visitor is assigned to. The key is set when you create the feature 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 variants
+## Configure allocation
 
-Each feature has one or more variants. Visitors are assigned to a variant based on the rules you define.
+Set the allocation from the detail page of the feature flag:
 
-Configure variant allocation, targeting rules, and rollout percentages from the feature detail page.
+| Control | What it does |
+| --- | --- |
+| **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. |
 
-## How visitors are bucketed
+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.
 
-Visitors are assigned to variants using weight-based probabilistic rollout. Each variant has a weight from 0 to 100, representing the percentage of traffic it receives.
+## How visitors are allocated
 
-For example, with two variants weighted 50/50, roughly half of visitors see each variant. A variant weighted at 0 receives no traffic.
+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.
 
-Bucketing is deterministic — the same visitor sees the same variant on repeat visits, unless the feature version changes.
+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).
 
-## Feature versions
+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%.
 
-Each feature has a version number (starting at 1). Incrementing the version resets all visitor assignments, so every visitor is re-evaluated as if they were seeing the feature for the first time.
+:::note
+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.
+:::
+
+## Turn a feature flag off
+
+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.
+
+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.
+
+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.
+
+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 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.
+:::
+
+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, 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
 
-- **All visitors are re-allocated.** Every visitor currently allocated to this feature will be re-evaluated against the new version. A visitor who was in the control group may end up in a variant, and vice versa.
-- **Cached decisions are invalidated.** The SDK caches allocation decisions in browser storage using a key that includes the version. When the version changes, the old cache entry no longer matches, forcing a fresh evaluation on the next page load.
-- **This is irreversible.** You cannot decrement a version. Once incremented, the previous allocation assignments are lost.
+- **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
+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 when you have changed the weight or allocation and want all visitors — including those already allocated — to be re-evaluated from scratch.
+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 only want changes to affect new visitors (those who haven't been allocated yet), update the weight without incrementing the version. Existing visitors will keep their current assignment.
+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.
 
-**Features** — the state of feature flags in your project. Use this to branch based on which variant a visitor is assigned to.
+**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**