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

package/dist/docs/pickedql/index.md

@@ -4,33 +4,51 @@ layout: docs
 
 # PickedQL
 
-PickedQL is a SQL query language for querying your Picked analytics data. Write simple SQL using virtual tables and functions — PickedQL expands them into optimized queries with automatic joins and A/B test aggregations.
+PickedQL is a SQL query language for your Picked analytics data. Write short SQL with
+a virtual table and a virtual function. PickedQL expands them into a full query, and
+it adds the joins and the A/B test aggregations for you.
 
 ## Quick start
 
 ```sql
--- How many users are in the control vs variant group?
+-- How many users are in the control group, and how many in the variant group?
 SELECT control_users(), variant_users()
 FROM metrics
 WHERE project_id = 'your-project-id'
 ```
 
-PickedQL handles table mapping and dimension joins automatically. You write concise, readable SQL — PickedQL does the rest.
+PickedQL maps each table and adds each dimension join for you. You write short SQL
+that a person can read, and PickedQL does the rest.
 
 ## How PickedQL works
 
-1. **Virtual table expansion**: Table names like `metrics` map to underlying data tables
-2. **Virtual function expansion**: Shorthand functions like `control_users()` expand to full aggregate expressions
-3. **Auto dimension joins**: References to dimension columns (like `device_category` or `country_code`) trigger automatic `LEFT JOIN` clauses — you never write joins yourself
-4. **Tenant isolation**: Every query must include a tenant filter in the `WHERE` clause — usually `project_id`, but `projects` uses `id` (the row's `id` IS the project id). PickedQL extracts the filter and verifies you have permission to access that project
-5. **SQL passthrough**: Standard SQL (including `CASE WHEN`, window functions, and subqueries) works alongside virtual functions
+1. **Virtual table expansion**: a table name such as `metrics` maps to the data
+   tables below it.
+2. **Virtual function expansion**: a short function such as `control_users()` expands
+   to a full aggregate expression.
+3. **Automatic dimension joins**: PickedQL adds a `LEFT JOIN` when you point at a
+   dimension column, such as `device_category` or `country_code`. You write no join.
+4. **Tenant isolation**: every query must hold a tenant filter in the `WHERE` clause.
+   That filter is `project_id` for most tables. The `projects` table uses `id`
+   instead, because the `id` of the row is the project ID. PickedQL reads the filter
+   and checks that you have permission for that project.
+5. **SQL passthrough**: standard SQL works next to a virtual function. This includes
+   `CASE WHEN`, a window function, and a subquery.
 
 ## Best practices
 
-- **Use `metrics` for dashboards**: Pre-aggregated data is significantly faster than raw events for standard reporting
-- **Use `events` for deep dives**: Raw event-level data gives full flexibility for custom breakdowns and funnels
-- **Use `experience_journey` for sankey / funnel charts**: One line of SQL returns `source, target, users` — the 8-CTE scaffold (dedup, top-N path ranking, lagInFrame) is handled internally; pass parameters via `WHERE`
-- **Don't write JOINs**: PickedQL injects them automatically when you reference dimension columns
-- **Group by any dimension**: Add dimension columns to `SELECT` and `GROUP BY` freely — required joins are handled for you
-- **Reference table metadata for free**: Use `step_title`, `experience_title`, `project_name` directly in `events` queries — PickedQL auto-joins the `steps`, `experiences`, and `projects` reference tables
+- **Use `metrics` for a dashboard**: data that PickedQL aggregates first is much
+  faster than raw events for a standard report.
+- **Use `events` to go deeper**: raw event data lets you build any breakdown or
+  funnel that you want.
+- **Use `experience_journey` for a sankey chart or a funnel chart**: one line of SQL
+  returns `source, target, users`. PickedQL builds the eight common table expressions
+  for you. Those remove the duplicates, rank the top paths, and call `lagInFrame`.
+  Pass your parameters in the `WHERE` clause.
+- **Write no JOIN**: PickedQL adds each one when you point at a dimension column.
+- **Group by any dimension**: add a dimension column to `SELECT` and to `GROUP BY`.
+  PickedQL adds the join that it needs.
+- **Read the reference tables for no cost**: use `step_title`, `experience_title`, and
+  `project_name` directly in an `events` query. PickedQL joins the `steps`,
+  `experiences`, and `projects` reference tables for you.
 

package/dist/docs/pickedql/schema.md

@@ -12,23 +12,23 @@ Pre-aggregated daily data. One row per unique combination of dimensions per day.
 
 | Column | Type | Description |
 |---|---|---|
-| `project_id` | String | Project identifier (required in `WHERE`) |
-| `project_local_date` | Date | Date in project timezone |
-| `experience_id` | String | Experience identifier |
-| `step_id` | String | Step identifier |
-| `event_type` | String | Event type (e.g., `page_view`, `click`) |
-| `interaction_type` | String | Interaction type (e.g., `Button Click`) |
-| `variant_type` | String | `Control`, `Variant`, or `Unknown` |
-| `device_category` | String | Device category (e.g., `Desktop`, `Mobile`) |
-| `country_code` | String | ISO country code |
-| `utm_source` | String | UTM source |
-| `utm_medium` | String | UTM medium |
-| `product_name` | String | Product name |
-| `product_category` | String | Product category |
-| `landing_page_url` | String | Landing page URL |
+| `project_id` | `String` | Project identifier (required in `WHERE`) |
+| `project_local_date` | `Date` | Date in project timezone |
+| `experience_id` | `String` | Experience identifier |
+| `step_id` | `String` | Step identifier |
+| `event_type` | `String` | Event type (for example `page_view`, `click`) |
+| `interaction_type` | `String` | Interaction type (for example `Button Click`) |
+| `variant_type` | `String` | `Control`, `Variant`, or `Unknown` |
+| `device_category` | `String` | Device category (for example `Desktop`, `Mobile`) |
+| `country_code` | `String` | ISO country code |
+| `utm_source` | `String` | UTM source |
+| `utm_medium` | `String` | UTM medium |
+| `product_name` | `String` | Product name |
+| `product_category` | `String` | Product category |
+| `landing_page_url` | `String` | Landing page URL |
 
 :::note
-Aggregate columns (`users`, `sessions`, `events`, etc.) are not queried directly — use [virtual functions](./virtual-functions) instead.
+Aggregate columns (`users`, `sessions`, `events`, and so on) are not queried directly — use [virtual functions](./virtual-functions) instead.
 :::
 
 ## `events`
@@ -39,22 +39,22 @@ User-level event data. One row per event per user. Dimension columns are joined
 
 | Column | Type | Description |
 |---|---|---|
-| `project_id` | String | Project identifier (required in `WHERE`) |
-| `event_id` | String | Unique event identifier |
-| `user_canonical_id` | String | Canonical user identifier |
-| `session_id` | String | Session identifier |
-| `experience_id` | String | Experience identifier |
-| `step_id` | String | Step identifier |
-| `event_type` | String | Event type (e.g., `page_view`, `click`) |
-| `interaction_type` | String | Interaction type (e.g., `Button Click`) |
-| `client_local_date` | Date | Date in client timezone |
-| `is_purchase` | UInt8 | `1` if checkout complete event |
-| `is_cart_add` | UInt8 | `1` if cart add event |
-| `is_first_session` | UInt8 | `1` if first session for this user |
-| `landing_page_url` | String | Landing page URL |
+| `project_id` | `String` | Project identifier (required in `WHERE`) |
+| `event_id` | `String` | Unique event identifier |
+| `user_canonical_id` | `String` | Canonical user identifier |
+| `session_id` | `String` | Session identifier |
+| `experience_id` | `String` | Experience identifier |
+| `step_id` | `String` | Step identifier |
+| `event_type` | `String` | Event type (for example `page_view`, `click`) |
+| `interaction_type` | `String` | Interaction type (for example `Button Click`) |
+| `client_local_date` | `Date` | Date in client timezone |
+| `is_purchase` | `UInt8` | `1` if checkout complete event |
+| `is_cart_add` | `UInt8` | `1` if cart add event |
+| `is_first_session` | `UInt8` | `1` if first session for this user |
+| `landing_page_url` | `String` | Landing page URL |
 | `features` | Map(String, String) | Feature flag assignments |
 | `feature_keys` | Map(String, String) | Feature key assignments |
-| `event_meta` | String | Event metadata |
+| `event_meta` | `String` | Event metadata |
 
 ### Dimension columns (auto-joined)
 
@@ -62,37 +62,39 @@ These columns are joined automatically when referenced — no `JOIN` syntax need
 
 | Column | Source | Description |
 |---|---|---|
-| `variant_type` | dim_variant | `Control`, `Variant`, or `Unknown` |
-| `ab_feature_name` | dim_variant | A/B feature name |
-| `ab_feature_value` | dim_variant | A/B feature value |
-| `device_category` | dim_device | Device category |
-| `browser_name` | dim_device | Browser name |
-| `browser_version` | dim_device | Browser version |
-| `os_name` | dim_device | Operating system name |
-| `os_version` | dim_device | Operating system version |
-| `platform` | dim_device | Platform |
-| `country_code` | dim_geo | ISO country code |
-| `country_name` | dim_geo | Country name |
-| `region` | dim_geo | Region |
-| `city` | dim_geo | City |
-| `utm_source` | dim_utm | UTM source |
-| `utm_medium` | dim_utm | UTM medium |
-| `utm_campaign` | dim_utm | UTM campaign |
-| `utm_term` | dim_utm | UTM term |
-| `utm_content` | dim_utm | UTM content |
-| `product_name` | dim_product | Product name |
-| `product_category` | dim_product | Product category |
-| `product_page` | dim_product | Product page |
-| `step_title` | steps | Step title (joined on `project_id` + `experience_id` + `step_id`) |
-| `experience_title` | experiences | Experience title (joined on `project_id` + `experience_id`) |
-| `project_name` | projects | Project name |
-| `project_timezone` | projects | Project timezone |
+| `variant_type` | `dim_variant` | `Control`, `Variant`, or `Unknown` |
+| `ab_feature_name` | `dim_variant` | A/B feature name |
+| `ab_feature_value` | `dim_variant` | A/B feature value |
+| `device_category` | `dim_device` | Device category |
+| `browser_name` | `dim_device` | Browser name |
+| `browser_version` | `dim_device` | Browser version |
+| `os_name` | `dim_device` | The name of the operating system |
+| `os_version` | `dim_device` | The version of the operating system |
+| `platform` | `dim_device` | Platform |
+| `country_code` | `dim_geo` | ISO country code |
+| `country_name` | `dim_geo` | Country name |
+| `region` | `dim_geo` | Region |
+| `city` | `dim_geo` | City |
+| `utm_source` | `dim_utm` | UTM source |
+| `utm_medium` | `dim_utm` | UTM medium |
+| `utm_campaign` | `dim_utm` | UTM campaign |
+| `utm_term` | `dim_utm` | UTM term |
+| `utm_content` | `dim_utm` | UTM content |
+| `product_name` | `dim_product` | Product name |
+| `product_category` | `dim_product` | Product category |
+| `product_page` | `dim_product` | Product page |
+| `step_title` | `steps` | Step title (joined on `project_id` + `experience_id` + `step_id`) |
+| `experience_title` | `experiences` | Experience title (joined on `project_id` + `experience_id`) |
+| `project_name` | `projects` | Project name |
+| `project_timezone` | `projects` | Project timezone |
 
 ## `steps`, `experiences`, `projects`
 
-Reference tables describing your Picked configuration. Auto-joined onto `events` when their analyst-facing columns are referenced; require a per-table tenant filter when queried directly.
+These reference tables hold the options of your Picked project. PickedQL joins them
+onto `events` when you point at one of their analyst-facing columns. Each one needs
+its own tenant filter when you read it directly.
 
-| Source | Real Columns | Analyst Columns (when referenced from `events`) | Tenant filter (when queried directly) |
+| Source | Real columns | Analyst columns, when you point at them from `events` | Tenant filter, when you read the table directly |
 |---|---|---|---|
 | `steps` | `id`, `title`, `experience_id`, `project_id`, `organization_id` | `step_title` | `project_id = '…'` |
 | `experiences` | `id`, `title`, `project_id`, `organization_id` | `experience_title` | `project_id = '…'` |
@@ -116,7 +118,9 @@ GROUP BY experience_title, step_title
 
 ## `features`
 
-The `features` table provides [parameterized virtual functions](./virtual-functions#feature-functions-features--events) for querying feature flag assignments:
+The `features` table gives you
+[parameterized virtual functions](./virtual-functions#feature-functions-on-features-and-on-events).
+Use them to read which visitors each feature flag holds:
 
 | Function | Description |
 |---|---|
@@ -126,31 +130,36 @@ The `features` table provides [parameterized virtual functions](./virtual-functi
 
 ## `experience_journey`
 
-Aggregated step-transition edges for sankey / funnel charts. Parameters are supplied via the outer `WHERE` clause (PickedQL extracts them and substitutes into the underlying scaffold).
+This table gives one edge for each step transition, and PickedQL aggregates them
+first. Use the edges in a sankey chart or a funnel chart. Give each parameter in the
+outer `WHERE` clause. PickedQL reads them and puts them into the query below.
 
 ### Columns
 
 | Column | Type | Description |
 |---|---|---|
-| `source` | String | Edge start, formatted as `NN. <step title>` (e.g., `001. Welcome screen`) |
-| `target` | String | Edge end, formatted as `NN. <step title>`. 
-| `users` | UInt64 | Distinct `user_canonical_id` count that traversed this edge. |
+| `source` | `String` | Edge start, formatted as `NN. <step title>` (for example `001. Welcome screen`) |
+| `target` | `String` | Edge end, formatted as `NN. <step title>`. 
+| `users` | `UInt64` | Distinct `user_canonical_id` count that traversed this edge. |
 
-### Parameters (via `WHERE`)
+### Parameters, in the `WHERE` clause
 
 | Key | Type | Required | Purpose |
 |---|---|---|---|
-| `project_id` | String | ✓ | Tenant filter. |
-| `experience_id` | String |  | Restrict to one `fact_events.experience_id`. |
-| `starting_step` | String |  | Anchor edges at first occurrence of this `step_id`. Defaults to each user's first step. |
-| `targeting_step` | String |  | Trim each user's window at their first occurrence of this `step_id`. Non-reachers still contribute their pre-cut journey. |
-| `num_nodes_after_start` | Integer |  | Forward window from start: keep steps where `seq_pos < start_seq + N` (card 4129 semantics). |
-| `num_nodes_before_target` | Integer |  | Backward window from target: keep steps where `seq_pos >= target_seq - N` (card 2740 semantics). Requires `targeting_step`. |
-| `top_n_path` | Integer |  | Keep only the top-N most-walked paths by user count. Defaults to no limit. |
-| `user_cohort_event` | String |  | Restrict to users who have at least one `fact_events` row with this `event_type`. Implemented as `user_canonical_id IN (SELECT DISTINCT user_canonical_id FROM fact_events WHERE event_type = '…')`. |
-| `client_local_date` | Date |  | Date range filter, pushed into the underlying scan. Supports `=`, `<`, `<=`, `>`, `>=`, `BETWEEN`. |
-| `event_timestamp` | DateTime64 |  | Server-side timestamp filter. Same operators as `client_local_date`. |
-
-When both window params are set, both predicates apply (intersection). Date filters combine via `AND` with the other params.
-
-See [data sources → experience_journey](./data-sources#experience_journey--sankey-ready-step-transitions) for usage examples.
+| `project_id` | `String` | ✓ | The tenant filter. |
+| `experience_id` | `String` |  | Limits the rows to one `fact_events.experience_id`. |
+| `starting_step` | `String` |  | Anchors each edge at the first time that a user reaches this `step_id`. The default is the first step of each user. |
+| `targeting_step` | `String` |  | Trims the window of each user at the first time that the user reaches this `step_id`. A user who never reaches it still gives the journey up to that point. |
+| `num_nodes_after_start` | Integer |  | The forward window from the start. It keeps a step where `seq_pos < start_seq + N`. This is what card 4129 does. |
+| `num_nodes_before_target` | Integer |  | The backward window from the target. It keeps a step where `seq_pos >= target_seq - N`. This is what card 2740 does. It needs `targeting_step`. |
+| `top_n_path` | Integer |  | Keeps the paths that the most users take, and drops the rest. The default is no limit. |
+| `user_cohort_event` | `String` |  | Limits the rows to a user with at least one `fact_events` row of this `event_type`. PickedQL writes it as `user_canonical_id IN (SELECT DISTINCT user_canonical_id FROM fact_events WHERE event_type = '…')`. |
+| `client_local_date` | `Date` |  | A filter on a range of dates. PickedQL puts it into the read below. It takes `=`, `<`, `<=`, `>`, `>=`, and `BETWEEN`. |
+| `event_timestamp` | `DateTime64` |  | A filter on the timestamp from the server. It takes the same operators as `client_local_date`. |
+
+When you set both window parameters, both tests apply, and the result is their
+intersection. A date filter joins the other parameters with `AND`.
+
+See
+[data sources, `experience_journey`](./data-sources#experience_journey--step-transitions-for-a-sankey-chart)
+for examples.

package/dist/docs/pickedql/virtual-functions.md

@@ -4,34 +4,41 @@ layout: docs
 
 # Virtual functions
 
-Virtual functions are shorthand for aggregate expressions. They are **table-aware** — the same function expands differently on `metrics` (pre-aggregated) vs `events` (user-level).
+A virtual function is a short form of an aggregate expression. Each one is
+**table-aware**. The same function expands one way on `metrics`, where PickedQL
+aggregates the data first. It expands another way on `events`, where there is one row
+for each user.
 
 ## A/B test metrics
 
 | Function | Description |
 |---|---|
-| `control_users([condition])` | Unique users in the Control group, optionally filtered by a custom condition |
-| `variant_users([condition])` | Unique users in the Variant group, optionally filtered by a custom condition |
-| `all_users()` | All unique users |
-| `control_sessions([condition])` | Unique sessions in the Control group, optionally filtered by a custom condition |
-| `variant_sessions([condition])` | Unique sessions in the Variant group, optionally filtered by a custom condition |
-| `all_sessions()` | All unique sessions |
+| `control_users([condition])` | The different users in the Control group. A condition of your own can narrow them. |
+| `variant_users([condition])` | The different users in the Variant group. A condition of your own can narrow them. |
+| `all_users()` | Every different user |
+| `control_sessions([condition])` | The different sessions in the Control group. A condition of your own can narrow them. |
+| `variant_sessions([condition])` | The different sessions in the Variant group. A condition of your own can narrow them. |
+| `all_sessions()` | Every different session |
 
-### Custom filters on `events`
+### Your own filters on `events`
 
-On the `events` table, `control_*`/`variant_*` functions accept **one optional filter argument** to count only users/sessions matching the given expression, in addition to the implicit `variant_type` filter. The argument can be **positional** or **named** (`filter=`).
+On the `events` table, each `control_*` function and each `variant_*` function takes
+**one optional filter argument**. The filter counts only a user or a session that
+matches your expression. It applies together with the `variant_type` filter that
+PickedQL adds. Give the argument in the first place, or by the name `filter=`.
 
-The filter uses the same `column=value` syntax as conversion-rate conditions, with `AND`/`OR` operators and parentheses for grouping.
+The filter uses the same `column=value` syntax as a conversion-rate condition. It
+takes the `AND` and `OR` operators, and parentheses can hold a set of terms.
 
 ```sql
--- Default: all Control users
+-- The default: every Control user.
 SELECT control_users() FROM events
 
--- Custom filter (positional)
+-- Your own filter, in the first place.
 SELECT control_users('event_type=app_initialize') FROM events
 SELECT variant_users('event_type=app_initialize AND step_id=xxx') FROM events
 
--- AND/OR + parentheses
+-- The AND and OR operators, with parentheses.
 SELECT control_users('event_type=app_initialize OR event_type=app_load') FROM events
 SELECT control_users('event_type=form_submit AND (step_id=lead-capture OR step_id=xxx)') FROM events
 
@@ -44,7 +51,9 @@ SELECT control_users(filter='event_type=app_initialize AND step_id=xxx') FROM ev
 ```
 
 :::note
-Custom filters are **not supported on `metrics`** (pre-aggregated data). On `metrics`, these functions ignore any arguments and use the default Control/Variant filter only.
+A filter of your own is **not supported on `metrics`**, because PickedQL aggregates
+that data first. On `metrics` these functions ignore every argument. They use the
+default Control filter and Variant filter only.
 :::
 
 ## Conversion metrics
@@ -62,15 +71,19 @@ Custom filters are **not supported on `metrics`** (pre-aggregated data). On `met
 
 | Function | Description |
 |---|---|
-| `control_conversion_rate([numerator [, denominator]])` | Conversion rate for Control. Defaults to purchase users / all users |
-| `variant_conversion_rate([numerator [, denominator]])` | Conversion rate for Variant. Same args as above |
-| `conversion_rate_uplift([numerator [, denominator]])` | Relative improvement: `(variant CR - control CR) / control CR`. Same args as above |
+| `control_conversion_rate([numerator [, denominator]])` | The conversion rate of the Control group. By default it divides the users with a purchase by all users. |
+| `variant_conversion_rate([numerator [, denominator]])` | The conversion rate of the Variant group. It takes the same arguments. |
+| `conversion_rate_uplift([numerator [, denominator]])` | The gain of the Variant over the Control: `(variant CR - control CR) / control CR`. It takes the same arguments. |
 
-### Custom conditions on `events`
+### Your own conditions on `events`
 
-On the `events` table, conversion rate functions accept up to **2 optional arguments** to customize the numerator and denominator. Each argument can be either a **condition expression string** or a **nested virtual function call** (see below). Arguments can be **positional** or **named** (`numerator=`, `denominator=`).
+On the `events` table, each conversion-rate function takes up to **two optional
+arguments**. They set the numerator and the denominator. Each argument is either a
+**condition expression string** or a **nested virtual function call**. See below.
+Give the arguments in order, or by the names `numerator=` and `denominator=`.
 
-Each condition expression uses `column=value` with `AND`/`OR` operators and parentheses for grouping.
+Each condition expression uses `column=value`, with the `AND` and `OR` operators.
+Parentheses can hold a set of terms.
 
 ```sql
 -- Default: purchase users / all users
@@ -79,11 +92,11 @@ SELECT control_conversion_rate() FROM events
 -- Custom numerator, default denominator (all users)
 SELECT control_conversion_rate('event_type=form_submit_success') FROM events
 
--- AND/OR in conditions
+-- The AND and OR operators in a condition.
 SELECT control_conversion_rate('event_type=checkout_complete OR event_type=order_create') FROM events
 SELECT control_conversion_rate('step_id=lead-capture AND event_type=form_submit_success') FROM events
 
--- Parentheses for grouping
+-- Parentheses hold a set of terms.
 SELECT control_conversion_rate('event_type=form_submit AND (step_id=lead-capture OR step_id=xxx)') FROM events
 
 -- Custom numerator AND denominator (positional)
@@ -95,18 +108,23 @@ SELECT control_conversion_rate(numerator='event_type=form_submit', denominator='
 -- Named: denominator only (numerator defaults to purchase)
 SELECT control_conversion_rate(denominator='step_id=lead-capture') FROM events
 
--- Uplift with named args
+-- The uplift, with the arguments given by name.
 SELECT conversion_rate_uplift(numerator='event_type=form_submit', denominator='step_id=lead-capture') FROM events
 ```
 
-#### Nested virtual functions as numerator / denominator
+#### A nested virtual function as the numerator or the denominator
 
-Instead of a condition string, you can pass a **virtual function call** as the numerator or denominator. The inner aggregate is substituted in place — no implicit `variant_type` filter is added on top of it (the nested function controls its own filter).
+You can pass a **virtual function call** as the numerator or the denominator, in
+place of a condition string. PickedQL puts the inner aggregate there directly. It
+adds no `variant_type` filter above it, because the nested function sets its own
+filter.
 
-This is the most flexible form when the numerator and denominator have different segments (e.g., Control users who fired event X over **all** users regardless of variant):
+This form is the most flexible one when the numerator and the denominator come from
+different segments. An example is the Control users who fired one event, over **all**
+users of every variant:
 
 ```sql
--- (Control users who fired app_initialize) / (all users)
+-- The Control users who fired `app_initialize`, over all users.
 SELECT control_conversion_rate(
   control_users('event_type=app_initialize'),
   all_users()
@@ -118,7 +136,7 @@ SELECT control_conversion_rate(
   all_users()
 ) FROM events
 
--- Uplift with nested args
+-- The uplift, with a nested function in each place.
 SELECT conversion_rate_uplift(
   control_users('event_type=app_initialize'),
   all_users()
@@ -126,7 +144,9 @@ SELECT conversion_rate_uplift(
 ```
 
 :::note
-Custom conditions and nested virtual function args are **not supported on `metrics`** (pre-aggregated data). On `metrics`, these functions always use the default purchase / all users definition.
+A condition of your own, and a nested virtual function, are both **not supported on
+`metrics`**, because PickedQL aggregates that data first. On `metrics` these
+functions always divide the users with a purchase by all users.
 :::
 
 ## Visitor segmentation (`metrics` only)
@@ -141,7 +161,7 @@ Custom conditions and nested virtual function args are **not supported on `metri
 ## Funnel metrics (`events` only)
 
 :::note
-Funnel metrics are being continuously updated. Check back for new functions.
+We add to the funnel metrics all the time. Read this page again for a new function.
 :::
 
 | Function | Description |
@@ -151,14 +171,18 @@ Funnel metrics are being continuously updated. Check back for new functions.
 
 ## Cohort filters (`events` only)
 
-Predicate-shaped functions that emit a `user_canonical_id IN (SELECT … FROM events …)` subquery. Use in `WHERE` to restrict any analysis to users who have at least one event matching a custom condition.
+Each of these functions has the shape of a predicate. It writes a
+`user_canonical_id IN (SELECT … FROM events …)` subquery. Put one in a `WHERE` clause
+to limit any analysis to a user with at least one event that matches a condition of
+your own.
 
 | Function | Description |
 |---|---|
-| `user_cohort_filter('<condition>')` | Restrict the query to users with ≥1 `events` row matching `<condition>` |
-| `user_cohort_filter(filter='<condition>')` | Same, named-arg form |
+| `user_cohort_filter('<condition>')` | Limits the query to a user with one or more `events` rows that match `<condition>` |
+| `user_cohort_filter(filter='<condition>')` | The same, with the argument given by name |
 
-`<condition>` uses the same `column=value [AND\|OR …]` shorthand as `control_users` / `variant_users`.
+`<condition>` uses the same short `column=value [AND\|OR …]` form as `control_users`
+and `variant_users`.
 
 ```sql
 -- Funnel scoped to users who eventually submitted lead capture
@@ -174,9 +198,11 @@ WHERE project_id = 'proj-abc'
   AND user_cohort_filter('event_type=signup OR event_type=trial_start')
 ```
 
-The outer query MUST filter by a single `project_id` — the function bakes that tenant into the inner subquery so the cohort scan is scoped to your project, not the whole warehouse.
+The outer query MUST hold one `project_id` filter. The function puts that tenant into
+the inner subquery. The read of the cohort therefore covers your project, and not the
+whole warehouse.
 
-## Feature functions (`features` / `events`)
+## Feature functions, on `features` and on `events`
 
 Parameterized functions that accept the feature name, bucket, and an optional feature key:
 

package/dist/docs/projects.mdx

@@ -6,16 +6,17 @@ import { Screenshot } from '../../components/Screenshot'
 
 # Projects
 
-A project represents one website or app you want to instrument with Picked. Each project has its own set of experiences, entities, and configuration.
+A project is one site or one application that you want to measure with Picked. Each
+project has its own experiences, entities, and options.
 
 <Screenshot
   route="/{orgSlug}"
-  alt="The organization home page on the Picked dashboard, listing the projects in an organization"
+  alt="The organization home page on the Picked dashboard, with the projects in an organization"
 />
 
 ## Create a project
 
-You need an organization first. If you don't have one, create it when you sign up.
+You need an organization first. If you do not have one, create it when you sign up.
 
 1. Open your organization.
 2. Click **New Project**.
@@ -24,14 +25,20 @@ You need an organization first. If you don't have one, create it when you sign u
 
 ## Workspaces
 
-Each project contains one or more [Workspaces](/workspaces) for configuring and previewing experiences before publishing.
+Each project holds one or more [Workspaces](/workspaces). In a workspace you set the
+options for an experience and you see a preview of it before you make it live.
 
 ## Project home
 
-When you open a project, you land on the project home page. It shows your SDK installation snippet and a getting-started checklist.
+When you open a project, you land on the project home page. It shows your SDK
+snippet and a list of the setup tasks that are still open.
 
-Copy the snippet and add it to your site. This connects your site to the project and enables experience delivery. See [SDK Installation](/sdk) for setup details.
+Copy the snippet and add it to your site. The snippet connects your site to the
+project and lets Picked serve experiences to it. See
+[SDK Installation](/sdk) for the setup detail.
 
 ## Project navigation
 
-The sidebar shows all sections available in your project: **Experiences**, **Fields**, **Steps**, **Actions**, **Conditions**, and more. Some sections appear only when enabled for your account.
+The sidebar shows every section of your project: **Experiences**, **Fields**,
+**Steps**, **Actions**, **Conditions**, and more. Some sections appear only when your
+account has them.

package/dist/docs/reports.mdx

@@ -6,13 +6,15 @@ import { Screenshot } from '../../components/Screenshot'
 
 # Reports
 
-Reports show analytics data for your project. Track how visitors interact with your experiences and feature flags.
+A report shows analytics data for your project. Use a report to track how your
+visitors use your experiences and feature flags.
 
 <Screenshot
   route="/{orgSlug}/{projectId}/reports"
   alt="The reports list for a project on the Picked dashboard"
 />
 
-## View report data
+## See report data
 
-Open a report to see its analytics. Data updates as new visitor interactions are recorded.
+Open a report to see its analytics. The data updates when Picked records a new
+visitor interaction.