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

package/dist/docs/mcp.md

@@ -4,21 +4,23 @@ layout: docs
 
 # MCP server
 
-Manage your Picked workspace from AI coding tools using the Model Context Protocol (MCP).
+Control your Picked workspace from an AI tool that writes code, with the Model
+Context Protocol (MCP).
 
-## Connecting
+## Connect
 
 The server URL is `https://api.picked.app/mcp`.
 
 ### Claude Desktop
 
-1. Open **Settings > Connectors > Add custom connector**
-2. Set **Name** to `Picked` and **URL** to `https://api.picked.app/mcp`
-3. Click **Connect** and complete the authorization prompt
+1. Open **Settings > Connectors > Add custom connector**.
+2. Set **Name** to `Picked` and **URL** to `https://api.picked.app/mcp`.
+3. Click **Connect** and answer the authorization prompt.
 
-### Project configuration (.mcp.json)
+### Project configuration in `.mcp.json`
 
-Add to your repository root. Works with Claude Code, Cursor, Windsurf, and other MCP-compatible tools.
+Add this file to the root of your repository. It works with Claude Code, Cursor,
+Windsurf, and other tools that support MCP.
 
 :::code-group
 
@@ -37,7 +39,7 @@ Add to your repository root. Works with Claude Code, Cursor, Windsurf, and other
 
 ### Cursor
 
-Add to `.cursor/mcp.json` in your project root:
+Add this file to `.cursor/mcp.json` in the root of your project:
 
 ```json
 {
@@ -50,25 +52,25 @@ Add to `.cursor/mcp.json` in your project root:
 }
 ```
 
-## Available tools
+## Tools
 
 ### Discovery
 
 | Tool                     | Description                                                  |
 | ------------------------ | ------------------------------------------------------------ |
-| `list_projects`          | List organizations and projects                              |
-| `get_workspace_overview` | Full workspace state                                         |
-| `get_schema_info`        | Documentation for Picked concepts and data model             |
-| `get_picked_docs`        | Fetch the complete Picked documentation (LLM-optimized text) |
+| `list_projects`          | Lists your organizations and projects                        |
+| `get_workspace_overview` | Reads the full workspace state                               |
+| `get_schema_info`        | Reads the documentation for Picked concepts and the data model |
+| `get_picked_docs`        | Reads the complete Picked documentation, as text for an agent |
 
 ### Experiences
 
 | Tool                     | Description                                                                               |
 | ------------------------ | ----------------------------------------------------------------------------------------- |
-| `create_experience`      | Create an experience                                                                      |
-| `get_experience`         | Get experience details including flow graph                                               |
-| `list_experiences`       | List experiences                                                                          |
-| `update_experience_flow` | Atomically create, update, or delete steps, conditions, actions, fields, nodes, and edges |
+| `create_experience`      | Creates an experience                                                                     |
+| `get_experience`         | Reads an experience, with its flow graph                                                  |
+| `list_experiences`       | Lists your experiences                                                                    |
+| `update_experience_flow` | Creates, updates, or deletes steps, conditions, actions, fields, nodes, and edges as one operation |
 
 ### Steps, fields, conditions, and actions
 
@@ -81,40 +83,46 @@ Add to `.cursor/mcp.json` in your project root:
 
 ### Feature flags
 
-| Tool             | Description                                        |
-| ---------------- | -------------------------------------------------- |
-| `create_feature` | Create a feature flag                              |
-| `get_feature`    | Get feature flag details                           |
-| `list_features`  | List feature flags                                 |
-| `update_feature` | Update name, description, enabled state, or weight |
+| Tool             | Description                                          |
+| ---------------- | ---------------------------------------------------- |
+| `create_feature` | Creates a feature flag                               |
+| `get_feature`    | Reads a feature flag                                 |
+| `list_features`  | Lists your feature flags                             |
+| `update_feature` | Updates the name, description, state, or weight      |
 
 ### Analytics
 
 | Tool             | Description                                                      |
 | ---------------- | ---------------------------------------------------------------- |
-| `query_pickedql` | Execute a PickedQL analytics query and return results as a table |
+| `query_pickedql` | Runs a PickedQL analytics query and returns the rows as a table  |
 
-Use `get_schema_info` with topic `pickedql` to see available tables, virtual functions, and dimension columns before writing queries.
+Call `get_schema_info` with the topic `pickedql` to see the tables, the virtual
+functions, and the dimension columns before you write a query.
 
-### Publishing
+### Publish
 
 | Tool                | Description                                    |
 | ------------------- | ---------------------------------------------- |
-| `get_preview_url`   | Generate a preview URL for unpublished changes |
-| `publish_workspace` | Publish the workspace                          |
+| `get_preview_url`   | Makes a preview URL for your unpublished work  |
+| `publish_workspace` | Publishes the workspace                        |
 
 ## Example prompts
 
-- "List my Picked projects and show me what's configured"
-- "Create a feature flag called 'new-checkout' enabled at 50% traffic"
-- "Create an experience with a step that collects email addresses"
-- "Show me control vs variant users by device for the last 30 days"
-- "Generate a preview URL for my workspace on https://example.com"
+- "List my Picked projects and show me the options on each one"
+- "Create a feature flag called 'new-checkout' at 50% traffic"
+- "Create an experience with a step that collects an email address"
+- "Show me control and variant users by the device type for the last 30 days"
+- "Make a preview URL for my workspace on `https://example.com`"
 
 ## Tips
 
-- Ask your agent to list your projects first, then explore your workspace to see what's configured.
-- When building complex experiences, ask your agent about flow graphs and JSON Logic — it can look up the documentation for you.
-- Experience flow updates are atomic — your agent can create steps, fields, nodes, and edges in a single operation.
-- Preview your changes on your site before publishing to verify everything looks right.
-- Ask your agent to query analytics data with PickedQL — it can look up the schema, write the SQL, and explain the results.
+- Ask your agent for a list of your projects first. Then ask it to read your
+  workspace and report the options on each record.
+- For a large experience, ask your agent about flow graphs and JSON Logic. The agent
+  can read the documentation for you.
+- An update to an experience flow is atomic. Your agent can create steps, fields,
+  nodes, and edges in one operation.
+- See a preview of your work on your site before you publish, to check that each page
+  is correct.
+- Ask your agent to run a PickedQL query on your analytics data. The agent can read
+  the schema, write the SQL, and explain the rows.

package/dist/docs/pickedql/data-sources.md

@@ -4,11 +4,14 @@ layout: docs
 
 # Data sources
 
-PickedQL provides four virtual tables (each optimized for different query patterns) plus three reference tables describing your Picked configuration.
+PickedQL gives you four virtual tables. Each table is fast for one kind of work. It also gives you three reference tables, and those hold the options of your
+Picked project.
 
-## `metrics` — Pre-aggregated daily data
+## `metrics` — data that PickedQL aggregates each day
 
-Best for dashboards and trend analysis. One row per unique combination of dimensions per day. Dimension columns (like `device_category`, `country_code`, `utm_source`) are available directly — no joins needed.
+Use it for a dashboard and to study a trend. There is one row for each unique set of
+dimensions on each day. The dimension columns are there directly, and they need no
+join. Examples are `device_category`, `country_code`, and `utm_source`.
 
 ```sql
 SELECT device_category, control_users(), variant_users()
@@ -17,9 +20,11 @@ WHERE project_id = 'your-project-id'
 GROUP BY device_category
 ```
 
-## `events` — User-level event data
+## `events` — one row for each event of each user
 
-Best for deep analysis, funnels, and custom breakdowns. One row per event per user. Dimension columns (like `device_category` or `country_code`) are joined automatically when referenced.
+Use it for a deep study, for a funnel, and for a breakdown of your own. There is one
+row for each event of each user. PickedQL joins a dimension column, such as
+`device_category` or `country_code`, when you point at it.
 
 ```sql
 SELECT user_canonical_id, device_category
@@ -28,9 +33,10 @@ WHERE project_id = 'your-project-id'
   AND variant_type = 'Control'
 ```
 
-## `features` — Feature flag analysis
+## `features` — one row for each feature flag
 
-Best for querying user, session, and event counts per feature flag and bucket. Uses parameterized functions.
+Use it to count the users, the sessions, and the events for each feature flag and
+bucket. It uses parameterized functions.
 
 ```sql
 SELECT feature_users('homepage_test', 'control')
@@ -38,40 +44,48 @@ FROM features
 WHERE project_id = 'your-project-id'
 ```
 
-## `experience_journey` — Sankey-ready step transitions
+## `experience_journey` — step transitions for a sankey chart
 
-Returns per-edge `source, target, users` rows ready to feed a sankey or funnel chart. Wraps the 8-CTE step-transition scaffold (lagInFrame, consecutive-step dedup, top-N path ranking) that cards used to carry inline.
+It returns one `source, target, users` row for each edge. You can put those rows
+directly into a sankey chart or a funnel chart. It holds the eight common table
+expressions that a card carried before. Those call `lagInFrame`, remove a duplicate
+between two steps that follow each other, and rank the top paths.
 
-All filters pass through the **outer `WHERE`** — PickedQL extracts them as parameters and substitutes them into the underlying scaffold. Only `project_id` is required; the rest are optional and default sensibly.
+Every filter goes in the **outer `WHERE`** clause. PickedQL reads each one as a
+parameter and puts it into the query below. Only `project_id` is necessary. The rest
+are optional, and each has a sensible default.
 
-| Param (WHERE key) | Purpose |
+| Parameter, as a WHERE key | What it does |
 |---|---|
-| `project_id` | Required tenant filter. |
-| `experience_id` | Restrict to one `fact_events.experience_id`. |
-| `starting_step` | Anchor edges at each user's first occurrence of this `step_id`. Absent → anchor at user's first step_enter event. |
-| `targeting_step` | Trim each user's window at their first occurrence of this `step_id`. Users who never reach it still contribute their journey up to `num_nodes_after_start`. |
-| `num_nodes_after_start` | Forward window size from the starting step (card 4129 semantics). |
-| `num_nodes_before_target` | Backward window size from the targeting step (card 2740 semantics). Requires `targeting_step`. |
-| `top_n_path` | Keep only the top-N distinct paths by user count. |
-| `user_cohort_event` | Restrict to users who have at least one `fact_events` row with this `event_type` (e.g., `'lead_capture'`). Useful for "paths taken by users who eventually converted". |
-| `client_local_date` | Date filter. Supports `=`, `<`, `<=`, `>`, `>=`, `BETWEEN`; pushed into the underlying `fact_events` scan. |
-| `event_timestamp` | Server-side timestamp filter. Same operators as `client_local_date`. |
-
-When `num_nodes_after_start` and `num_nodes_before_target` are both set, both predicates apply (intersection).
+| `project_id` | The tenant filter. It is necessary. |
+| `experience_id` | Limits the rows to one `fact_events.experience_id`. |
+| `starting_step` | Anchors each edge at the first time that a user reaches this `step_id`. With no value, it anchors at the first `step_enter` event of that user. |
+| `targeting_step` | 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 a journey, up to `num_nodes_after_start`. |
+| `num_nodes_after_start` | The size of the forward window from the start step. This is what card 4129 does. |
+| `num_nodes_before_target` | The size of the backward window from the target step. This is what card 2740 does. It needs `targeting_step`. |
+| `top_n_path` | Keeps the paths with the most users, and drops the rest. |
+| `user_cohort_event` | Limits the rows to a user with at least one `fact_events` row of this `event_type`, such as `'lead_capture'`. Use it for the paths of the users who reached a goal. |
+| `client_local_date` | A filter on the date. It takes `=`, `<`, `<=`, `>`, `>=`, and `BETWEEN`. PickedQL puts it into the `fact_events` read below. |
+| `event_timestamp` | A filter on the timestamp from the server. It takes the same operators as `client_local_date`. |
+
+When you set both `num_nodes_after_start` and `num_nodes_before_target`, both tests
+apply. The result is the intersection of the two.
 
 ```sql
--- "Overall user journey" sankey (card 4129 pattern) — forward window, target optional
+-- The "overall user journey" sankey, as in card 4129.
+-- It uses a forward window. The target step is optional.
 SELECT source, target, users FROM experience_journey
 WHERE project_id           = 'your-project-id'
   AND starting_step        = 'step-start'
   AND targeting_step       = 'step-target'
   AND num_nodes_after_start = 10
-  AND client_local_date   >= '2026-04-01'    -- optional date range
+  AND client_local_date   >= '2026-04-01'    -- An optional range of dates.
   AND client_local_date   <= '2026-04-30'
 ```
 
 ```sql
--- "Paths leading to target" sankey (card 2740 pattern) — backward window + top-N ranking
+-- The "paths to a target" sankey, as in card 2740.
+-- It uses a backward window and it ranks the top paths.
 SELECT source, target, users FROM experience_journey
 WHERE project_id             = 'your-project-id'
   AND experience_id          = 'exp-123'
@@ -82,7 +96,7 @@ WHERE project_id             = 'your-project-id'
 ```
 
 ```sql
--- "Drop-off" sankey (card 2744 pattern) — omit targeting_step
+-- The "drop-off" sankey, as in card 2744. Leave the target step out.
 SELECT source, target, users FROM experience_journey
 WHERE project_id           = 'your-project-id'
   AND experience_id        = 'exp-123'
@@ -91,55 +105,63 @@ WHERE project_id           = 'your-project-id'
 ```
 
 ```sql
--- Cohort sankey: only users who eventually converted (card 3961 pattern)
+-- A cohort sankey, as in card 3961. It holds the users who reached the goal only.
 SELECT source, target, users FROM experience_journey
 WHERE project_id           = 'your-project-id'
   AND starting_step        = 'step-start'
   AND targeting_step       = 'step-target'
   AND num_nodes_after_start = 10
-  AND user_cohort_event    = 'lead_capture'   -- restrict to users with ≥1 lead_capture event
+  AND user_cohort_event    = 'lead_capture'   -- Users with one or more of these events.
 ```
 
-Columns returned:
+The columns that it returns:
 
 | Column | Type | Description |
 |---|---|---|
-| `source` | String | Edge start, formatted as `NN. <step title>` (e.g., `001. Welcome screen`). PickedQL joins `steps` to resolve the title. |
-| `target` | String | Edge end, formatted as `NN. <step title>`. |
-| `users` | UInt64 | Distinct `user_canonical_id` count that traversed this edge. |
+| `source` | String | The start of the edge, in the form `NN. <step title>`, such as `001. Welcome screen`. PickedQL joins `steps` to find the title. |
+| `target` | String | The end of the edge, in the form `NN. <step title>`. |
+| `users` | `UInt64` | The number of different `user_canonical_id` values that went along this edge. |
 
 :::note
-`experience_journey` is aggregated output. Dimension filters (`variant_type`, `device_category`, `country_code`, …) are **not** supported — if you need those, query [`events`](#events--user-level-event-data) directly and build the transitions yourself.
+`experience_journey` returns data that PickedQL aggregates first. It does **not**
+support a dimension filter such as `variant_type`, `device_category`, or
+`country_code`. To use one of those, query
+[`events`](#events--one-row-for-each-event-of-each-user) directly and build the
+transitions yourself.
 :::
 
 ## Reference tables — `steps`, `experiences`, `projects`
 
-Reference tables describing your Picked configuration. They serve two roles:
+These reference tables hold the options of your Picked project. They have two uses:
 
-- **Auto-joined onto `events`** when their prefixed analyst columns (`step_title`, `experience_title`, `project_name`, `project_timezone`) are referenced.
-- **Queryable directly**, with a per-table tenant filter required so you only see rows belonging to a project you have access to.
+- **PickedQL joins them onto `events`** when you point at one of their analyst
+  columns: `step_title`, `experience_title`, `project_name`, or `project_timezone`.
+- **You can read them directly.** Each one then needs its own tenant filter, so that
+  you see only the rows of a project that you can reach.
 
-| Source | Tenant filter required |
+| Source | The tenant filter that it needs |
 |---|---|
 | `steps` | `WHERE project_id = '<project_id>'` |
 | `experiences` | `WHERE project_id = '<project_id>'` |
 | `projects` | `WHERE id = '<project_id>'` |
 
 ```sql
--- Direct query: list experiences for a project
+-- A direct query that reads the experiences of a project.
 SELECT id, title FROM experiences WHERE project_id = 'your-project-id'
 
--- Direct query: load metadata for one project
+-- A direct query that reads the metadata of one project.
 SELECT id, name, timezone FROM projects WHERE id = 'your-project-id'
 ```
 
 ```sql
--- Referenced from events: PickedQL auto-injects the LEFT JOINs
--- (no separate tenant filter on the reference tables — the join is scoped via fact_events)
+-- Pointed at from events. PickedQL adds each LEFT JOIN for you.
+-- The reference tables need no separate tenant filter, because
+-- the event table already limits the join.
 SELECT experience_title, step_title, count(*)
 FROM events
 WHERE project_id = 'your-project-id'
 GROUP BY experience_title, step_title
 ```
 
-See [Schema → reference tables](./schema#steps-experiences-projects) for the full column list and join keys.
+See [Schema, reference tables](./schema#steps-experiences-projects) for the full
+column list and the join keys.

package/dist/docs/pickedql/dimensions.md

@@ -4,9 +4,11 @@ layout: docs
 
 # Dimension columns
 
-Dimension columns are available on all data sources. On `metrics`, they are included directly in the table. On `events` and `features`, the required `LEFT JOIN` is added automatically when you reference them — you never write joins yourself.
+Every data source has dimension columns. The `metrics` table holds them directly. On
+`events` and on `features`, PickedQL adds the `LEFT JOIN` that it needs when you
+point at one. You write no join.
 
-## Available dimensions
+## The dimensions
 
 | Source | Columns |
 |---|---|
@@ -19,29 +21,42 @@ Dimension columns are available on all data sources. On `metrics`, they are incl
 | `experiences` | `experience_title` |
 | `projects` | `project_name`, `project_timezone` |
 
-The `steps`, `experiences`, and `projects` sources are reference tables sourced from the operational database. They are auto-joined onto `events`/`fact_events` when their analyst-facing columns are referenced, **and** they require their own tenant filter when queried directly:
+The `steps`, `experiences`, and `projects` sources are reference tables, and they come
+from the operational database. PickedQL joins them onto `events` and `fact_events`
+when you point at one of their analyst-facing columns. Each one **also** needs its own
+tenant filter when you query it directly:
 
-| Source | Tenant filter required |
+| Source | The tenant filter that it needs |
 |---|---|
 | `steps`, `experiences` | `WHERE project_id = '<project_id>'` |
-| `projects` | `WHERE id = '<project_id>'` (the row's `id` IS the project id) |
+| `projects` | `WHERE id = '<project_id>'`, because the `id` of the row is the project ID |
 
-When auto-joined, these reference tables also receive a tenant equality on the JOIN's `ON` clause (e.g. `AND st.project_id = '<project_id>'`, `AND pr.id = '<project_id>'`) so ClickHouse prunes the dim scan instead of reading the full table. The predicate is added to `ON` rather than `WHERE` to preserve `LEFT JOIN` semantics.
+PickedQL also puts a tenant equality in the `ON` clause of each join that it adds.
+Examples are `AND st.project_id = '<project_id>'` and `AND pr.id = '<project_id>'`.
+ClickHouse then reads part of the dimension table and not all of it. PickedQL puts
+the test in `ON` and not in `WHERE`, because a test in `WHERE` would change a
+`LEFT JOIN` into an inner join.
 
-Analyst-facing column names are prefixed (`step_title`, `project_name`, etc.) to avoid collisions across sources — for example, `steps.title` and `experiences.title` both exist, but you reference them as `step_title` and `experience_title`.
+Each analyst-facing column name carries a prefix, such as `step_title` and
+`project_name`. The prefix stops a collision between two sources. Both `steps.title`
+and `experiences.title` are there, and you point at them as `step_title` and
+`experience_title`.
 
 ```sql
--- Group events by experience and step name (auto-joins both `experiences` and `steps`)
+-- Group the events by experience and by step name.
+-- PickedQL joins both `experiences` and `steps` for you.
 SELECT experience_title, step_title, count(*)
 FROM events
 WHERE project_id = 'your-project-id'
 GROUP BY experience_title, step_title
 ```
 
-Auto-joins also work inside subqueries and CTEs — reference dimension columns wherever you need them and the required `LEFT JOIN` is injected at that level:
+An automatic join also works inside a subquery and inside a common table expression.
+Point at a dimension column where you need it, and PickedQL adds the `LEFT JOIN` at
+that level:
 
 ```sql
--- Dimension columns inside a CTE
+-- Dimension columns inside a common table expression.
 WITH per_step AS (
   SELECT step_title, count(*) AS n
   FROM events
@@ -50,7 +65,7 @@ WITH per_step AS (
 )
 SELECT * FROM per_step ORDER BY n DESC
 
--- Dimension columns inside a nested SELECT
+-- Dimension columns inside a nested query.
 SELECT step_title, n FROM (
   SELECT step_title, count(*) AS n FROM events
   WHERE project_id = 'your-project-id'
@@ -60,6 +75,6 @@ SELECT step_title, n FROM (
 
 ## Native event columns
 
-These columns are available directly on `events` and require no join:
+These columns are on `events` directly, and they need no join:
 
 `event_type`, `interaction_type`, `experience_id`, `step_id`, `event_id`, `user_canonical_id`, `session_id`, `client_local_date`, `is_purchase`, `is_cart_add`, `event_meta`.

package/dist/docs/pickedql/examples.md

@@ -51,7 +51,9 @@ ORDER BY project_local_date
 
 ## Custom conversion rate definition
 
-Override the default purchase conversion with your own numerator and denominator. Useful when conversion is defined by a form submission, lead capture, or any custom event.
+Override the default conversion, which counts a `purchase` event, with your own
+numerator and denominator. Use this when a form submission, a lead capture, or
+another event of your own defines a conversion.
 
 ```sql
 -- Lead capture conversion: form submissions / lead-capture step entries
@@ -75,7 +77,7 @@ ORDER BY project_local_date
 You can also combine multiple events with `OR` and group with parentheses:
 
 ```sql
--- Either checkout_complete or order_create counts as a conversion
+-- A `checkout_complete` event or an `order_create` event counts as a conversion.
 SELECT
   control_conversion_rate(
     'event_type=checkout_complete OR event_type=order_create'
@@ -87,12 +89,15 @@ FROM events
 WHERE project_id = '{{ your project ID }}'
 ```
 
-## Custom segment with `control_users` / `variant_users`
+## Your own segment with `control_users` and `variant_users`
 
-On `events`, `control_users` / `variant_users` / `control_sessions` / `variant_sessions` accept an optional filter string to count only users/sessions matching the given expression in addition to the implicit `variant_type` filter.
+On `events`, four functions take an optional filter string: `control_users`,
+`variant_users`, `control_sessions`, and `variant_sessions`. The filter counts only a
+user or a session that matches your expression. It applies together with the
+`variant_type` filter that PickedQL adds.
 
 ```sql
--- Control users who fired app_initialize, broken down by step
+-- The control users who fired an `app_initialize` event, by step.
 SELECT
   step_id,
   control_users('event_type=app_initialize')                      AS control_initialized,
@@ -113,10 +118,13 @@ WHERE project_id = '{{ your project ID }}'
 
 ## Conversion rate from nested virtual functions
 
-When numerator and denominator come from different segments — e.g., Control users who fired a custom event divided by **all** users (not just Control) — pass virtual function calls directly as conversion-rate args:
+The numerator and the denominator can come from different segments. An example is the
+control users who fired an event of your own, divided by **all** users and not by the
+control users alone. For that, pass a virtual function call directly as an argument
+of the conversion rate:
 
 ```sql
--- (Control users who fired app_initialize) / (all users, regardless of variant)
+-- The control users who fired `app_initialize`, over all users of every variant.
 SELECT
   control_conversion_rate(
     control_users('event_type=app_initialize'),
@@ -188,9 +196,9 @@ GROUP BY utm_source
 
 | utm_source | users  | purchasers |
 | ---------- | ------ | ---------- |
-| meta       | 12031  | 101        |
-| fb         | 3656   | 31         |
-| an         | 100366 | 299        |
+| `meta`       | 12031  | 101        |
+| `fb`         | 3656   | 31         |
+| `an`         | 100366 | 299        |
 
 ## Step funnel for variant users
 
@@ -211,18 +219,20 @@ ORDER BY variant DESC
 
 | step_id                        | variant |
 | ------------------------------ | ------- |
-| who-are-you-protecting-step    | 1093    |
-| about-yourself-step            | 533     |
-| date-of-birth-step             | 435     |
-| employment-status-step         | 408     |
-| nicotine-usage-step            | 407     |
-| coverage-motivation-step       | 405     |
-| lead-capture-step              | 398     |
+| `who-are-you-protecting-step`    | 1093    |
+| `about-yourself-step`            | 533     |
+| `date-of-birth-step`             | 435     |
+| `employment-status-step`         | 408     |
+| `nicotine-usage-step`            | 407     |
+| `coverage-motivation-step`       | 405     |
+| `lead-capture-step`              | 398     |
 
 
 ## Sankey — overall user journey
 
-Forward window from the starting step. Non-reachers of `targeting_step` still contribute edges up to `num_nodes_after_start`. Mirrors dashboard 1156 card 4129's semantics.
+A forward window from the starting step. A user who never reaches `targeting_step`
+still gives edges, up to `num_nodes_after_start`. This does what card 4129 on
+dashboard 1156 does.
 
 ```sql
 SELECT source, target, users FROM experience_journey
@@ -236,13 +246,15 @@ WHERE project_id            = '{{ your project ID }}'
 
 | source                    | target                    | users |
 | ------------------------- | ------------------------- | ----- |
-| 001. step-start           | 002. step-questionnaire-1 | 182   |
-| 002. step-questionnaire-1 | 003. step-quote           | 144   |
-| 003. step-quote           | 004. step-target          | 121   |
+| `001. step-start`           | `002. step-questionnaire-1` | 182   |
+| `002. step-questionnaire-1` | `003. step-quote`           | 144   |
+| `003. step-quote`           | `004. step-target`          | 121   |
 
-## Sankey — top paths leading to a target step
+## Sankey — the top paths to a target step
 
-Backward window anchored at the target, plus top-N path ranking. Mirrors dashboard 1156 card 3961 / dashboard 991 card 2740 semantics.
+A backward window anchored at the target. It also ranks the paths and keeps the ones
+with the most users. This does what card 3961 on dashboard 1156 and card 2740 on
+dashboard 991 do.
 
 ```sql
 SELECT source, target, users FROM experience_journey
@@ -284,6 +296,6 @@ WHERE project_id = '{{ your project ID }}'
 
 | device_category | user_canonical_id                    |
 | --------------- | ------------------------------------ |
-| Mobile          | 019cc336-5a6a-7c32-b638-cdcc983b3e70 |
-| Mobile          | 019cc336-5a6a-7d8f-994c-69bc28e5f550 |
-| Mobile          | 019cc80f-503c-7181-b2c6-986b1f76d496 |
+| Mobile          | `019cc336-5a6a-7c32-b638-cdcc983b3e70` |
+| Mobile          | `019cc336-5a6a-7d8f-994c-69bc28e5f550` |
+| Mobile          | `019cc80f-503c-7181-b2c6-986b1f76d496` |

package/dist/docs/pickedql/filtering.md

@@ -2,17 +2,19 @@
 layout: docs
 ---
 
-# Filtering
+# Filters
 
-Add `WHERE` clauses as usual. Every query must include a `project_id` filter — PickedQL extracts it and verifies you have permission to access that project. Queries without a `project_id` filter are rejected.
+Add a `WHERE` clause in the usual way. Every query must hold a `project_id` filter.
+PickedQL reads that filter and checks that you have permission for the project.
+PickedQL rejects a query with no `project_id` filter.
 
 ```sql
--- Date range
+-- A range of dates.
 SELECT control_users() FROM metrics
 WHERE project_id = 'your-project-id'
   AND project_local_date BETWEEN '2026-03-01' AND '2026-03-31'
 
--- By experience
+-- By experience.
 SELECT step_enter_users() FROM events
 WHERE project_id = 'your-project-id'
   AND experience_id = 'my-experience'
@@ -30,9 +32,11 @@ WHERE project_id = 'your-project-id'
 Each query can only filter on a single `project_id`. Queries that reference multiple projects will be rejected.
 :::
 
-## Reference tables (per-table tenant filter)
+## Reference tables, each with its own tenant filter
 
-Queries against the reference tables (`steps`, `experiences`, `projects`) require their own tenant filter so you only see rows belonging to a project you have access to:
+A query against a reference table needs its own tenant filter. The reference tables
+are `steps`, `experiences`, and `projects`. The filter makes sure that you see only
+the rows of a project that you can reach:
 
 | Source | Tenant filter |
 |---|---|