@picked/client 0.0.70-next.5 → 0.0.70

package/dist/docs/image-optimisation-service.md

@@ -4,7 +4,10 @@ layout: docs
 
 # Image optimisation service
 
-The Picked image optimisation service is a hosted endpoint at `https://img.picked-content.com`. It fetches images from allowed source domains, resizes them, re-encodes to modern formats (WebP or AVIF), and caches the result.
+The Picked service for image optimisation is a hosted endpoint at
+`https://img.picked-content.com`. It reads an image from an allowed source domain and
+resizes it. It then encodes the image again to a modern format, WebP or AVIF, and
+caches the result.
 
 ## Endpoint
 
@@ -14,35 +17,39 @@ GET https://img.picked-content.com/_next/image?url={source}&w={width}&q={quality
 
 | Parameter | Description |
 |-----------|-------------|
-| `url` | URL-encoded URL of the source image. Must point to an allowed source domain (see below). |
-| `w` | Target width in pixels. Must match one of the supported widths. |
-| `q` | Target quality (`25`, `50`, `75`, or `100`). |
+| `url` | The URL of the source image, URL-encoded. It must point at an allowed source domain. See below. |
+| `w` | The width in pixels. It must be one of the supported widths. |
+| `q` | The quality: `25`, `50`, `75`, or `100`. |
 
-The service performs content negotiation: if the requesting browser advertises `image/avif` or `image/webp` in its `Accept` header, the response uses that format. Otherwise the response uses the source format.
+The service chooses the response format. When the browser advertises `image/avif` or
+`image/webp` in its `Accept` header, the response uses that format. If it does not,
+the response uses the source format.
 
 ## Allowed source domains
 
-The service only fetches from these hostnames:
+The service reads only from these hostnames:
 
 - `**.picked.app`
 
-A request whose `url` parameter resolves to any other hostname returns `400 Bad Request`.
+A request with a `url` parameter for any other hostname returns `400 Bad Request`.
 
 ## Supported widths
 
-Device sizes, for responsive images that span the viewport width:
+Device sizes, for a responsive image that spans the width of the viewport:
 
 ```
 640, 750, 828, 1080, 1200, 1920, 2048, 3840
 ```
 
-Image sizes, for fixed-size UI elements such as icons, avatars, and thumbnails:
+Image sizes, for a UI element of fixed size such as an icon, an avatar, or a
+thumbnail:
 
 ```
 16, 32, 48, 64, 96, 128, 256, 384
 ```
 
-Requests with any other width return `400 Bad Request`. Pick the smallest width that covers your target rendering size at the user's device pixel ratio.
+A request with any other width returns `400 Bad Request`. Choose the smallest width
+that covers the size you render at the device pixel ratio of the visitor.
 
 ## Supported qualities
 
@@ -50,11 +57,13 @@ Requests with any other width return `400 Bad Request`. Pick the smallest width
 25, 50, 75, 100
 ```
 
-Lower values reduce bandwidth significantly. `75` is a good default for most images; use `25` or `50` for thumbnails on slow networks.
+A lower value reduces the bandwidth by a large amount. `75` is a good default for
+most images. Use `25` or `50` for a thumbnail on a slow network.
 
 ## Responsive images
 
-Combine the endpoint with the standard `srcset` attribute to let browsers pick the right width per viewport:
+Use the endpoint together with the standard `srcset` attribute. The browser then
+picks the correct width for each viewport:
 
 ```html
 <img
@@ -69,12 +78,19 @@ Combine the endpoint with the standard `srcset` attribute to let browsers pick t
 />
 ```
 
-## Caching
+## Cache
 
-Optimised responses are cached by the upstream CDN. The minimum cache TTL is 60 seconds; the actual lifetime depends on the CDN's eviction policy. If you change the source image at the same URL, expect the optimised variant to remain cached for at least that interval.
+The upstream CDN caches each optimised response. The smallest cache TTL is 60
+seconds. The real lifetime depends on the eviction policy of the CDN. When you change
+the source image at the same URL, the optimised copy stays in the cache for at least
+that time.
 
 ## Security
 
-- SVG sources are not optimised. Requests for SVG return the original bytes if the source is allowed; the service never executes embedded scripts.
-- Optimised responses carry a strict `Content-Security-Policy` (`default-src *; script-src 'none'; sandbox;`) so even a compromised source cannot run scripts in a viewing browser.
-- The response uses `Content-Disposition: inline`, never `attachment`.
+- The service does not optimise an SVG source. A request for an SVG returns the
+  original bytes when the source is allowed. The service never runs an embedded
+  script.
+- Each optimised response carries a strict `Content-Security-Policy`
+  (`default-src *; script-src 'none'; sandbox;`). A compromised source therefore
+  cannot run a script in the browser that shows the image.
+- The response uses `Content-Disposition: inline`, and never `attachment`.

package/dist/docs/index.md

@@ -2,25 +2,29 @@
 layout: docs
 ---
 
-# Getting Started
+# Start here
 
-Picked lets you build personalized UI flows in a visual editor and deliver them to visitors on your site with a lightweight SDK.
+Picked lets you build personalized UI flows in a visual editor. The SDK then serves
+them to the visitors on your site.
 
 ## How it works
 
-You design experiences in the dashboard using a drag-and-drop flow builder. The SDK fetches your published experiences and renders them on your site.
+You build experiences in the dashboard with a drag-and-drop flow builder. The SDK
+reads your published experiences and renders them on your site.
 
 ## Quick start
 
 ### 1. Create a project
 
-Sign in to the dashboard and create a project. A project represents one website or app.
+Sign in to the dashboard and create a project. A project is one site or one
+application.
 
-See [Projects](/projects) for details.
+See [Projects](/projects) for more detail.
 
 ### 2. Install the SDK
 
-Add the SDK to your site and initialize the client. Copy the snippet from your project home page.
+Add the SDK to your site and start the client. Copy the snippet from your project
+home page.
 
 ```typescript
 import { createClient } from '@picked/client'
@@ -33,11 +37,12 @@ const picked = createClient({
 picked.start()
 ```
 
-See [SDK Installation](/sdk) for full setup options.
+See [SDK Installation](/sdk) for all setup options.
 
 ### 3. Register a component
 
-Register components when creating the client. Each key in the `components` object must match a component name you set in the dashboard.
+Register your components when you create the client. Each key in the `components`
+object must match a component name that you set in the dashboard.
 
 ```typescript
 import { createClient } from '@picked/client'
@@ -52,26 +57,32 @@ const picked = createClient({
 picked.start()
 ```
 
-See [SDK Experiences](/sdk/experiences) for targeting, conditions, and component adapters.
+See [SDK Experiences](/sdk/experiences) for conditions, adapters, and the rules that
+put an experience in a slot.
 
 ### 4. Create an experience
 
-In the dashboard, open your project and click **Experiences** > **New Experience**. Enter a name and set the component name to match your registered component (e.g., `welcome-survey`).
+In the dashboard, open your project. Click **Experiences**, then **New Experience**.
+Enter a name. Set the component name to match your registered component, for example
+`welcome-survey`.
 
-See [Experiences](/experiences) for configuration options.
+See [Experiences](/experiences) for the options.
 
 ### 5. Build the flow
 
-Open the flow builder and drag steps, actions, and conditions onto the canvas. Connect nodes to define the visitor's path through the experience.
+Open the flow builder. Drag steps, actions, and conditions onto the canvas. Connect
+the nodes to define the path that a visitor takes through the experience.
 
-See [Flow Builder](/flow-builder/overview) for a full walkthrough.
+See [Flow Builder](/flow-builder/overview) for a full guide.
 
 ### 6. Save and publish
 
-Click **Save** in the flow builder toolbar. The SDK picks up the published experience and renders it to matching visitors on your site.
+Click **Save** in the flow builder toolbar. The SDK reads the published experience
+and renders it to each visitor who matches.
 
 ## Next steps
 
-- [Flow Builder](/flow-builder/overview) — Build experience flows visually
-- [Steps](/steps), [Fields](/fields), [Actions](/actions), [Conditions](/conditions) — Configure the building blocks of experiences
-- [SDK Installation](/sdk) — Full SDK setup and configuration
+- [Flow Builder](/flow-builder/overview) — Build experience flows in a visual editor
+- [Steps](/steps), [Fields](/fields), [Actions](/actions), [Conditions](/conditions)
+  — Set up the parts of an experience
+- [SDK Installation](/sdk) — Full SDK setup and options

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`.