@picked/client 0.0.71-next.1 → 0.0.71-next.2

package/dist/docs/reference/delivery-api/index.md

@@ -0,0 +1,45 @@
+---
+type: reference
+layout: docs
+---
+
+# Delivery API
+
+The Delivery API is a public REST API. It is read-only, and it serves the published
+configuration of your project together with your page content. It is separate from the
+GraphQL management API.
+
+## Base URL and versioning
+
+All Delivery API routes are versioned under `/api/v1`:
+
+```
+https://api.picked.app/api/v1
+```
+
+## Published content and preview content
+
+Each endpoint serves two surfaces:
+
+- **Published** content is anonymous. Anybody can read your published configuration and
+  your published content.
+- **Preview** content needs a `preview_token` query parameter. With it you can render
+  an unpublished draft before you make it live.
+
+The management API holds the preview token of a workspace in the `previewToken`
+field. The preview action in the dashboard also makes one for you.
+
+## Endpoints
+
+| Endpoint | Description |
+| --- | --- |
+| [Project Config](/reference/delivery-api/project-config) | `GET /api/v1/projects/:projectId` returns the published configuration of the project, with the content link of each step. |
+| [Experience Content](/reference/delivery-api/experience-content) | `GET /api/v1/projects/:projectId/experiences/:id/content` returns the Content Entries of an experience. |
+
+Both endpoints share some behaviour. See
+[Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling).
+
+## Related
+
+- [About the two APIs](/explanation/the-two-apis) — which one to use, and why they are
+  separate.

package/dist/docs/{delivery-api → reference/delivery-api}/preview-caching-crawling.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -16,10 +17,10 @@ and both return `versionId: null` for a preview. An invalid token returns `401`.
 curl "https://api.picked.app/api/v1/projects/proj_123?preview_token=<token>"
 ```
 
-The [management API](/api) holds the preview token of a workspace in the
+The [management API](/tutorials/first-api-call) holds the preview token of a workspace in the
 `previewToken` field. The preview action in the dashboard also makes one for you.
 
-Use the same token for the project options request and for the experience content
+Use the same token for the project configuration request and for the experience content
 request. Both then come from the same preview.
 
 ## Cache
@@ -57,7 +58,7 @@ the `robots.txt` rules:
 ```
 User-agent: *
 
-# Let a crawler read the public project options and experience content.
+# Let a crawler read the public project configuration and experience content.
 Allow: /api/v1/projects
 Allow: /api/v1/projects/*/experiences/*/content
 
@@ -68,5 +69,11 @@ Disallow: /api/v1/projects/*preview_token=
 Disallow: /
 ```
 
-See [Project Config](/delivery-api/project-config) and
-[Experience Content](/delivery-api/experience-content) for the endpoints.
+See [Project Config](/reference/delivery-api/project-config) and
+[Experience Content](/reference/delivery-api/experience-content) for the endpoints.
+
+## Related
+
+- [About the two APIs](/explanation/the-two-apis) — how a preview stays out of the search
+  index.
+- [How to render an unpublished preview](/how-to/render-an-unpublished-preview)

package/dist/docs/{delivery-api → reference/delivery-api}/project-config.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -15,11 +16,11 @@ GET /api/v1/projects/:projectId
 | Parameter | In | Description |
 | --- | --- | --- |
 | `projectId` | path | The project to fetch config for. |
-| `preview_token` | query | Optional. With it, the endpoint returns the preview options, which are unpublished. |
+| `preview_token` | query | Optional. With it, the endpoint returns the preview configuration, which are unpublished. |
 
 ## Response
 
-The response carries the project's experiences and steps. Each step includes `layoutContentId`, the reference to the Content Entry that backs that step's layout. Use it to know which experiences have content to fetch from the [Experience Content](/delivery-api/experience-content) endpoint.
+The response carries the project's experiences and steps. Each step includes `layoutContentId`, the reference to the Content Entry that backs that step's layout. Use it to know which experiences have content to fetch from the [Experience Content](/reference/delivery-api/experience-content) endpoint.
 
 | Field | Type | Description |
 | --- | --- | --- |
@@ -31,7 +32,7 @@ The response carries the project's experiences and steps. Each step includes `la
 
 For published content, `versionId` holds the ID of the published version. For preview
 content, which you read with `?preview_token=...`, `versionId` is `null`, because
-there is no published version. See [Preview, cache, and crawlers](/delivery-api/preview-caching-crawling).
+there is no published version. See [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling).
 
 ## Example
 
@@ -55,4 +56,10 @@ curl https://api.picked.app/api/v1/projects/proj_123
 }
 ```
 
-Pass the config to `serialize()` on your server to produce an SSR snapshot. See [Server Snapshot](/sdk/ssr/serialize).
+Pass the config to `serialize()` on your server to produce an SSR snapshot. See [Server Snapshot](/reference/sdk/ssr/serialize).
+
+## Related
+
+- [About the two APIs](/explanation/the-two-apis)
+- [Experience content](/reference/delivery-api/experience-content)
+- [How to server-render a page](/how-to/server-render-a-page)

package/dist/docs/reference/glossary.md

@@ -0,0 +1,173 @@
+---
+type: reference
+layout: docs
+---
+
+# Glossary
+
+Every term that Picked uses, and what each one means. The dashboard, the API, and the SDK
+sometimes use different words for the same thing. This page gives the word that the
+documentation uses, and it names the others.
+
+## Accounts and access
+
+| Term | What it is |
+| --- | --- |
+| **Organization** | The top level. It holds your projects, your members, and your settings. You can belong to more than one. |
+| **Member** | A person in an organization. Each member holds one role. |
+| **Role** | What a member can reach. It decides whether a member can create a project, edit an experience, or read a report. |
+| **API key** | A credential for a server-to-server integration. It belongs to an organization, it can belong to one project, and it carries scopes. |
+| **Scope** | One permission, written `resource/action`, such as `organization/read`. A scope decides which operations a caller can do. |
+| **Session** | The result of a sign-in. It holds an access token, a refresh token, and the time at which the access token expires. |
+| **User** | A person who signs in to the Picked dashboard. A user is not a visitor. |
+| **Invitation** | An offer to join an organization, sent to an email address. It waits until the person accepts it. |
+| **MFA factor** | A second credential on an account, such as a telephone number. |
+
+## Projects and versions
+
+| Term | What it is |
+| --- | --- |
+| **Project** | One site or one application. Each project has its own experiences, content, and configuration. |
+| **Project configuration** | The published settings of a project: its experiences and steps, and the content link on each step. The Delivery API serves it, and the SDK reads it. The SDK parameter is `projectConfig`. |
+| **Workspace** | One version of the configuration of a project. You hold a change in a workspace, see a preview of it, and publish it. |
+| **Draft** | A workspace that no visitor sees. |
+| **Live** | The workspace whose snapshot the SDK serves. Each project has exactly one. |
+| **Archived** | A draft that you put to one side. It is still editable, and it is out of the default list. |
+| **Version** | An immutable snapshot of a workspace, made when you publish. The **Publish history** page lists them. |
+| **Preview** | A view of an unpublished workspace on your own site. It reaches your browser only. |
+| **Preview environment** | A named target that a preview opens against. |
+| **Project settings** | The settings of one project, which you edit in the dashboard. These are not the project configuration that the Delivery API serves. |
+
+## Experiences
+
+| Term | What it is |
+| --- | --- |
+| **Experience** | Personalized content that Picked serves to a visitor. It is a Flow or a Page. |
+| **Flow** | An interactive experience of more than one step, which the browser renders. |
+| **Page** | A standalone experience that your server renders from a content entry, for content that a search engine must read. |
+| **Step** | One screen that a visitor sees. It holds fields. |
+| **Field** | A data input inside a step. It collects a name, an email address, a preference, or a choice. |
+| **Field option** | One choice in a field that has a fixed set of choices. Each option carries a value, and it can carry a condition. |
+| **Action** | A side effect that starts when the flow reaches it. Your application registers a handler for it. |
+| **Condition** | A rule that decides whether a visitor sees something, or which branch a flow takes. |
+| **Predicate** | A function that you register on the client, so a condition can read data that only your application holds. |
+| **Response** | A value that a visitor sends through a field. |
+| **Origin** | The node where every flow starts. |
+| **Node** | One part of a flow on the canvas: an origin, a step, an action, or a condition. |
+| **Handle** | A connection point on a node. An input handle is on the left, an output handle on the right. |
+| **Key** | The stable identifier of a step, a field, an action, or a condition. Your application and your API calls both use it. You set it one time, and you cannot change it. |
+| **Layout name** | The name of the component that renders a step, such as `card` or `modal`. |
+| **Target** | The element that an experience renders against, found by its target selector. |
+
+## Feature flags
+
+| Term | What it is |
+| --- | --- |
+| **Feature flag** | A control that decides which visitors see a change, so you can run an A/B test or release in stages. The API type is `Feature`. |
+| **Weight** | The percentage of visitors that Picked allocates to a feature flag, from 0 to 100. |
+| **Allocation** | The act that puts a visitor in a feature flag. It happens when something first reads the bucket. |
+| **Bucket** | The value a feature flag resolves to for one visitor. |
+| **Exposure** | The moment a visitor enters a test. It is the same moment as the allocation. |
+| **Version** | A number on a feature flag that forms part of the cache key. It is not part of the allocation. |
+
+## Content
+
+| Term | What it is |
+| --- | --- |
+| **Page layout** | A reusable schema that sets which fields a Page can hold. The API type is `ContentModel`, and the dashboard list page is titled **Models**. |
+| **Step layout** | The same, for one Step inside a Flow. |
+| **Section** | A reusable schema fragment that you put inside one or more layouts. The API type is `ContentBlock`, and the dashboard list page is titled **Blocks**. |
+| **Content entry** | One instance of a layout, filled with real values. The dashboard list page is titled **Content**. |
+| **Asset** | A file that your content points at: an image, a video, a document, or HTML. |
+| **Asset library** | The project-level store that holds your assets. |
+| **Design system** | A set of shared design decisions for a project. |
+| **Content schema** | The set of fields that a layout or a section defines. |
+| **Asset version** | One file that somebody uploaded for an asset. The library keeps the earlier versions. |
+| **Validation error** | A report that one field in a content entry does not match its schema. It carries the path to the exact field. |
+
+## The SDK
+
+| Term | What it is |
+| --- | --- |
+| **Client** | The object that `createClient()` returns. It holds your configuration and runs the experiences. |
+| **Plugin** | A piece of behaviour that you pass to the `plugins` array of the client. |
+| **Component name** | The identifier that points an experience at a component in your application. |
+| **Adapter** | The function that lets the client render a framework component: `adaptReactComponent` or `adaptSvelteComponent`. |
+| **Slot** | A named mount point, rendered by `<ExperienceSlot name="…" />`. It maps to the `.picked-slot-<name>` selector. |
+| **Placement** | Where an experience renders against its target: `replace`, `before`, `prepend`, `append`, or `after`. |
+| **Target selector** | The selector that an experience renders into. |
+| **Snapshot** | The plain JSON that `serialize()` returns on your server, and that seeds the client in the browser. |
+| **Precondition** | A gate that decides whether Picked starts at all. |
+| **Visitor** | The person on your site. Picked gives each one a stable ID. A visitor is not a user. |
+| **Framework plugin** | The plugin that lets the client render a React or a Svelte component. |
+
+## APIs and analytics
+
+| Term | What it is |
+| --- | --- |
+| **Delivery API** | The public, anonymous, read-only REST API that serves your published configuration and content. |
+| **Management API** | The authenticated GraphQL API that controls your projects, experiences, and content. |
+| **Preview token** | A token that lets a Delivery API request read unpublished content. |
+| **PickedQL** | The SQL query language for your Picked analytics data. |
+| **Virtual table** | A table name in PickedQL, such as `metrics`, that maps to the real tables below it. |
+| **Virtual function** | A short function in PickedQL, such as `control_users()`, that expands to a full aggregate expression. |
+| **Dimension** | A column that PickedQL joins for you, such as `device_category`. |
+| **Report** | An embedded analytics dashboard or question, attached to a project. |
+
+## Tools
+
+| Term | What it is |
+| --- | --- |
+| **MCP connection** | A link between a Picked project and an AI tool, over the Model Context Protocol. The dashboard calls this **MCP connections**. |
+| **Integration** | A connection between Picked and another service. |
+| **Tag ID** | The identifier of a project, which the template for Google Tag Manager uses. |
+
+## Verbs
+
+The actions that Picked names, and what each one does. Where an API mutation uses the
+word exactly, the table says so.
+
+### You act on the dashboard
+
+| Verb | What it does |
+| --- | --- |
+| **Create** | Makes a new record. |
+| **Update** | Changes a record that exists. |
+| **Delete** | Removes a record permanently. You cannot reverse it. |
+| **Publish** | Makes an immutable snapshot of a workspace and serves it to your visitors. |
+| **Archive** | Moves a draft workspace out of the default list. It stays editable. |
+| **Unarchive** | Returns an archived workspace to the default list. |
+| **Duplicate** | Copies a workspace, and everything in it, into a new draft. |
+| **Restore** | Moves the live pointer of a project to an earlier version. It changes no data. |
+| **Preview** | Opens your site with an unpublished workspace applied, for your browser only. |
+| **Invite** | Sends an invitation to join an organization. |
+| **Revoke** | Invalidates an API key or an invitation immediately. |
+| **Install** | Connects an integration to your project. |
+
+### Picked acts on a visitor
+
+| Verb | What it does |
+| --- | --- |
+| **Allocate** | Puts a visitor in a feature flag. |
+| **Resolve** | Gives a feature flag its bucket for one visitor. The first read resolves it. |
+| **Decide** | Runs the `decide` function of a feature flag. |
+| **Evaluate** | Runs a condition against the current state. |
+| **Invoke** | Calls a predicate from inside a condition. |
+| **Serve** | Sends published content to a visitor. |
+
+### Your code acts on the SDK
+
+| Verb | What it does |
+| --- | --- |
+| **Register** | Adds a component, an action, a predicate, or a feature flag to the client. |
+| **Start** | Runs the client. `start()` is idempotent. |
+| **Adapt** | Wraps a framework component so the client can render it. |
+| **Serialize** | Builds a snapshot on your server, with `serialize()`. |
+| **Seed** | Gives the client a snapshot, so the first render matches the server. |
+| **Hydrate** | Takes over the server markup in the browser. |
+| **Render** | Puts a component into the page. |
+
+## Related
+
+- [About how Picked works](/explanation/how-picked-works) — how these parts fit together.
+- [Projects](/reference/dashboard/projects) — the dashboard surface.

package/dist/docs/reference/management-api/authentication.md

@@ -0,0 +1,74 @@
+---
+type: reference
+layout: docs
+---
+
+# Authentication
+
+The Picked API supports four ways to authenticate. They are a session from an email
+address and a password, an OAuth provider, a magic link, and an API key. This guide
+covers each one. It also covers how to control a session and how to use multi-factor
+authentication (MFA).
+
+## Use a session
+
+After the caller has a session, it puts the access token in the `Authorization`
+header of every request that needs authentication:
+
+```
+Authorization: Bearer <accessToken>
+```
+
+The `expiresAt` field of the session gives the time at which the access token
+expires. The caller must refresh the session before that time.
+
+### Authenticator assurance levels
+
+The session holds an `aal` field, and it gives the strength of the authentication:
+
+| Level | Meaning |
+|-------|---------|
+| `AAL1` | One factor: an email address and a password, OAuth, or a magic link |
+| `AAL2` | More than one factor: the user completed an MFA challenge |
+
+Some operations need `AAL2`. When a caller at `AAL1` tries one of them, the API
+returns an authorization error.
+
+## The mutations
+
+| Mutation | What it does |
+| --- | --- |
+| `sessionCreate` | Authenticates an email address and a password. Returns a session, or `requiresMfa`. |
+| `sessionRefresh` | Exchanges a refresh token for a new session. Needs no `Authorization` header. |
+| `accountCreate` | Creates an account. `metadata` takes any JSON. |
+| `accountVerifyEmail` | Completes email verification with the token from the email. |
+| `accountResendVerification` | Sends the verification email again. |
+| `oauthAuthorize` | Returns the authorization URL for a provider. Google is supported. |
+| `oauthCallback` | Exchanges an OAuth code for a session. |
+| `magicLinkSend` | Sends a sign-in link to an email address. |
+| `magicLinkVerify` | Exchanges a magic-link token for a session. |
+| `passwordResetSend` | Sends a password reset email. |
+| `passwordReset` | Completes a reset with the token from the email. |
+| `passwordUpdate` | Changes a password. Needs authentication. |
+| `mfaFactorEnroll` | Adds an MFA factor. A new factor is `UNVERIFIED`. |
+| `mfaChallengeSend` | Sends a code to the telephone number of the factor. |
+| `mfaChallengeVerify` | Verifies a challenge. Moves the session to `AAL2`. |
+| `mfaFactorUnenroll` | Removes an MFA factor. |
+| `apiKeyCreate` | Creates an API key. Only a user with a session can call it. |
+| `apiKeyRevoke` | Invalidates a key immediately. |
+
+## Credentials
+
+| Credential | Header |
+| --- | --- |
+| Session access token | `Authorization: Bearer <accessToken>` |
+| API key | `x-api-key: pk_live_abc123...` |
+
+## Related
+
+- [How to authenticate with a password](/how-to/authenticate-with-a-password)
+- [How to authenticate with OAuth](/how-to/authenticate-with-oauth)
+- [How to authenticate with a magic link](/how-to/authenticate-with-a-magic-link)
+- [How to set up MFA](/how-to/set-up-mfa)
+- [How to authenticate with an API key](/how-to/authenticate-with-an-api-key)
+- [Authorization and scopes](/reference/management-api/authorization-and-scopes)

package/dist/docs/{api → reference/management-api}/authorization-and-scopes.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -11,7 +12,7 @@ and how the API resolves a permission.
 
 ## The format of a scope name
 
-A scope has the form `entity/action`:
+A scope has the form `resource/action`:
 
 ```
 organization/read
@@ -19,7 +20,7 @@ organization_members/create
 organization_projects/delete
 ```
 
-- **entity** — a lowercase name. It uses an underscore between words, as in
+- **resource** — a lowercase name. It uses an underscore between words, as in
   `organization_members` and `organization_api_keys`.
 - **action** — one of `create`, `read`, `update`, or `delete`.
 
@@ -150,7 +151,7 @@ the scope inside that organization. For a root-level operation such as
 `organizationCreate`, the API resolves the scope at the account level.
 
 When the caller does not hold the scope that an operation needs, the API returns an
-authorization error with the code `FORBIDDEN`. See [Errors](./error-handling.md).
+authorization error with the code `FORBIDDEN`. See [Errors](/reference/management-api/error-handling).
 
 ## Operations and required scopes
 
@@ -276,3 +277,9 @@ Response:
 Use this to build a UI that changes with the permissions of the caller. An example is
 a **Delete Organization** button that the UI hides when the caller does not hold
 `ORGANIZATION_DELETE`.
+
+## Related
+
+- [Authentication](/reference/management-api/authentication)
+- [How to authenticate with an API key](/how-to/authenticate-with-an-api-key)
+- [API keys](/reference/dashboard/api-keys) — the dashboard surface.

package/dist/docs/{api → reference/management-api}/error-handling.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -45,7 +46,7 @@ operation, or MFA. They match the `AuthErrorCode` enum in the schema.
 | Code | Description |
 |------|-------------|
 | `INVALID_CREDENTIALS` | The email address and the password do not match. |
-| `EMAIL_NOT_CONFIRMED` | The account is there, but nobody verified the email address. See [Authentication](/api/authentication#verify-an-email-address). |
+| `EMAIL_NOT_CONFIRMED` | The account is there, but nobody verified the email address. See [Authentication](/reference/management-api/authentication#verify-an-email-address). |
 | `USER_NOT_FOUND` | There is no account with that email address. |
 | `USER_ALREADY_EXISTS` | An account with that email address is there already. The API returns this when you create an account. |
 | `WEAK_PASSWORD` | The password is not strong enough. |
@@ -82,7 +83,7 @@ operation, or MFA. They match the `AuthErrorCode` enum in the schema.
 ## Authorization error codes
 
 An authorization error happens when the caller does not hold the
-[scope](./authorization-and-scopes.md) that an operation needs.
+[scope](/reference/management-api/authorization-and-scopes) that an operation needs.
 
 | Code | Description |
 |------|-------------|
@@ -198,7 +199,7 @@ if (result.errors) {
 ### Refresh a token that expired
 
 A request can return `UNAUTHORIZED` while the caller holds a refresh token. Try a
-[session refresh](/api/authentication#refresh-a-session) first. Do not treat it as a
+[session refresh](/reference/management-api/authentication#refresh-a-session) first. Do not treat it as a
 failure to sign in:
 
 ```javascript
@@ -225,3 +226,8 @@ both.
 `INTERNAL_ERROR` and `RATE_LIMITED` are both transient. For `RATE_LIMITED`, use an
 exponential backoff before you try again. For `INTERNAL_ERROR`, one more try is
 usually enough.
+
+## Related
+
+- [Authentication](/reference/management-api/authentication)
+- [Your first API call](/tutorials/first-api-call)

package/dist/docs/{api → reference/management-api}/pagination.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -184,3 +185,8 @@ All of these fields accept the same `first` and `after` arguments and return the
 - **Use them with other fields** — you can use the pagination arguments together with
   other query fields. One request that reads an organization and the first page of
   its members is common, and it is efficient.
+
+## Related
+
+- [Your first API call](/tutorials/first-api-call)
+- [Authorization and scopes](/reference/management-api/authorization-and-scopes)

package/dist/docs/{pickedql → reference/pickedql}/data-sources.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -61,8 +62,8 @@ are optional, and each has a sensible default.
 | `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`. |
+| `num_nodes_after_start` | The size of the forward window from the start step. |
+| `num_nodes_before_target` | The size of the backward window from the target step. 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. |
@@ -72,7 +73,7 @@ When you set both `num_nodes_after_start` and `num_nodes_before_target`, both te
 apply. The result is the intersection of the two.
 
 ```sql
--- The "overall user journey" sankey, as in card 4129.
+-- The "overall user journey" sankey.
 -- It uses a forward window. The target step is optional.
 SELECT source, target, users FROM experience_journey
 WHERE project_id           = 'your-project-id'
@@ -84,7 +85,7 @@ WHERE project_id           = 'your-project-id'
 ```
 
 ```sql
--- The "paths to a target" sankey, as in card 2740.
+-- The "paths to a target" sankey.
 -- It uses a backward window and it ranks the top paths.
 SELECT source, target, users FROM experience_journey
 WHERE project_id             = 'your-project-id'
@@ -96,7 +97,7 @@ WHERE project_id             = 'your-project-id'
 ```
 
 ```sql
--- The "drop-off" sankey, as in card 2744. Leave the target step out.
+-- The "drop-off" sankey. Leave the target step out.
 SELECT source, target, users FROM experience_journey
 WHERE project_id           = 'your-project-id'
   AND experience_id        = 'exp-123'
@@ -105,7 +106,7 @@ WHERE project_id           = 'your-project-id'
 ```
 
 ```sql
--- A cohort sankey, as in card 3961. It holds the users who reached the goal only.
+-- A cohort sankey. 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'
@@ -132,7 +133,7 @@ transitions yourself.
 
 ## Reference tables — `steps`, `experiences`, `projects`
 
-These reference tables hold the options of your Picked project. They have two uses:
+These reference tables hold the configuration of your Picked project. They have two uses:
 
 - **PickedQL joins them onto `events`** when you point at one of their analyst
   columns: `step_title`, `experience_title`, `project_name`, or `project_timezone`.
@@ -163,5 +164,11 @@ 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 the join keys.
+See [Schema, reference tables](/reference/pickedql/schema#steps-experiences-projects) for the full
+column list and the join keys.
+
+## Related
+
+- [About PickedQL](/explanation/how-pickedql-works) — what the layer expands for you.
+- [Schema](/reference/pickedql/schema)
+- [Analytics queries](/how-to/analytics)

package/dist/docs/{pickedql → reference/pickedql}/dimensions.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -78,3 +79,9 @@ SELECT step_title, n FROM (
 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`.
+
+## Related
+
+- [About PickedQL](/explanation/how-pickedql-works) — why you write no join.
+- [Data sources](/reference/pickedql/data-sources)
+- [Analytics queries](/how-to/analytics)

package/dist/docs/{pickedql → reference/pickedql}/filtering.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -55,3 +56,9 @@ SELECT id, name, timezone FROM projects WHERE id = 'your-project-id'
 ```
 
 The small lookup tables (`dim_variant`, `dim_device`, `dim_geo`, `dim_utm`, `dim_product`) are still exempt — they contain no tenant data.
+
+## Related
+
+- [Virtual functions](/reference/pickedql/virtual-functions) — the functions that take a
+  filter.
+- [Analytics queries](/how-to/analytics)

package/dist/docs/reference/pickedql/index.md

@@ -0,0 +1,18 @@
+---
+type: reference
+layout: docs
+---
+
+# PickedQL
+
+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.
+
+## Related
+
+- [About PickedQL](/explanation/how-pickedql-works) — what the layer expands, and why a
+  tenant filter is required.
+- [Analytics queries](/how-to/analytics) — worked examples.
+- [Data sources](/reference/pickedql/data-sources) — every table.
+- [Filters](/reference/pickedql/filtering) — the filter string a virtual function takes.

package/dist/docs/{pickedql → reference/pickedql}/schema.md

@@ -1,4 +1,5 @@
 ---
+type: reference
 layout: docs
 ---
 
@@ -28,7 +29,7 @@ Pre-aggregated daily data. One row per unique combination of dimensions per day.
 | `landing_page_url` | `String` | Landing page URL |
 
 :::note
-Aggregate columns (`users`, `sessions`, `events`, and so on) 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](/reference/pickedql/virtual-functions) instead.
 :::
 
 ## `events`
@@ -90,7 +91,7 @@ These columns are joined automatically when referenced — no `JOIN` syntax need
 
 ## `steps`, `experiences`, `projects`
 
-These reference tables hold the options of your Picked project. PickedQL joins them
+These reference tables hold the configuration 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.
 
@@ -119,7 +120,7 @@ GROUP BY experience_title, step_title
 ## `features`
 
 The `features` table gives you
-[parameterized virtual functions](./virtual-functions#feature-functions-on-features-and-on-events).
+[parameterized virtual functions](/reference/pickedql/virtual-functions#feature-functions-on-features-and-on-events).
 Use them to read which visitors each feature flag holds:
 
 | Function | Description |
@@ -150,8 +151,8 @@ outer `WHERE` clause. PickedQL reads them and puts them into the query below.
 | `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`. |
+| `num_nodes_after_start` | Integer |  | The forward window from the start. It keeps a step where `seq_pos < start_seq + N`. |
+| `num_nodes_before_target` | Integer |  | The backward window from the target. It keeps a step where `seq_pos >= target_seq - N`. 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`. |
@@ -161,5 +162,11 @@ 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)
+[data sources, `experience_journey`](/reference/pickedql/data-sources#experience_journey--step-transitions-for-a-sankey-chart)
 for examples.
+
+## Related
+
+- [Data sources](/reference/pickedql/data-sources)
+- [Dimensions](/reference/pickedql/dimensions)
+- [About PickedQL](/explanation/how-pickedql-works)