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

package/dist/docs/flow-builder/nodes.md

@@ -1,43 +0,0 @@
----
-layout: docs
----
-
-# Nodes
-
-Nodes are the building blocks of a flow. Each node represents a block in your experience. There are four node types.
-
-## Origin
-
-Every flow starts with an origin node. It's a gray circle on the left side of the canvas. It has one output handle on its right side.
-
-You can't move, delete, or duplicate the origin. It's always present.
-
-## Step
-
-A step node represents a screen shown to visitors. It appears as a blue rectangle on the canvas.
-
-Steps hold fields. Drag a field from the entity browser onto a step node to assign it. The node subtitle shows how many fields are assigned.
-
-Each step has a `layoutName` that tells the SDK which visual layout to use when rendering this step. Configure the layout name in the inspector.
-
-## Action
-
-An action node represents a side effect — something that happens behind the scenes. It appears as a green rectangle.
-
-Actions trigger when the flow reaches them. Use actions for tasks like tracking events, sending data, or triggering integrations.
-
-## Condition
-
-A condition node represents a branching point. It appears as an amber rectangle.
-
-Condition nodes have two output handles instead of one. The green handle (top-right) connects to the path taken when the condition is true. The red handle (bottom-right) connects to the path taken when it's false.
-
-Define the condition logic in the inspector using the visual condition builder. See [Conditions](/conditions) for details.
-
-## Handles
-
-Handles are the connection points on nodes. Input handles sit on the left. Output handles sit on the right. Drag from an output handle to an input handle to connect two nodes.
-
----
-
-[Overview](/flow-builder/overview) · **Nodes** · [Building Flows](/flow-builder/building-flows) · [Keyboard Shortcuts](/flow-builder/keyboard-shortcuts) · [Condition Builder](/flow-builder/condition-builder)

package/dist/docs/flow-builder/overview.mdx

@@ -1,50 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../../components/Screenshot'
-
-# Flow builder
-
-The flow builder is a visual editor for designing experience flows. You drag blocks onto a canvas, connect them with arrows, and configure each node in an inspector panel.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/experiences/{experienceId}"
-  alt="The flow builder with the entity browser, canvas, and inspector panels"
-/>
-
-## Layout
-
-The flow builder has three panels arranged left to right.
-
-**Entity browser** (left): Lists all steps, actions, conditions, and fields in your project. Drag items from here onto the canvas.
-
-**Canvas** (center): The workspace where you build your flow. Nodes represent blocks. Arrows represent connections between them.
-
-**Inspector** (right): Shows configuration for the selected node. When nothing is selected, it shows experience-level settings.
-
-## Panel controls
-
-Drag the dividers between panels to resize them. Press `Cmd/Ctrl+\` to toggle both side panels. Press `Cmd/Ctrl+Shift+\` to toggle just the inspector.
-
-## Navigating the canvas
-
-**Zoom**: Scroll to zoom in and out.
-
-**Pan**: Select the hand tool (press `H`) and drag. Or hold `Space` while dragging. Middle-click drag also pans.
-
-**Select tool**: Press `V` to switch back to the select tool. This is the default — click to select nodes, drag on empty space to marquee-select.
-
-## Auto-layout
-
-Click the auto-layout button in the toolbar to automatically arrange all nodes in a clean hierarchy. Useful after adding many nodes or when the canvas gets messy.
-
-## Saving
-
-Click **Save** in the toolbar to save your flow. The button is enabled when you have unsaved changes.
-
-The flow builder also auto-saves after a period of inactivity. A dot indicator appears on the save button when there are unsaved changes.
-
----
-
-**Flow Builder** · [Nodes](/flow-builder/nodes) · [Building Flows](/flow-builder/building-flows) · [Keyboard Shortcuts](/flow-builder/keyboard-shortcuts) · [Condition Builder](/flow-builder/condition-builder)

package/dist/docs/gtm-template.md

@@ -1,69 +0,0 @@
----
-layout: docs
----
-
-# Google Tag Manager template
-
-The Picked Ecommerce GTM Tag Template lets you track ecommerce events and send them to Picked directly from Google Tag Manager.
-
-## Automatic installation
-
-Install the template from the GTM Community Gallery:
-
-1. In Tag Manager, click **Templates**.
-2. In the **Tag Templates** section, click **Search Gallery**.
-3. Search for `Picked Ecommerce`.
-4. Click the Picked Ecommerce template to view details.
-5. Click **Add to workspace**.
-6. Review the required permissions and click **Add**.
-
-![Picked Ecommerce template in the GTM Community Gallery](/gtm/picked-ecommerce-gtm.png)
-
-## Manual installation
-
-If you prefer to import the template file directly:
-
-1. Download the [template file](https://github.com/picked-app/gtm-template/blob/main/template.tpl) from GitHub (use the download icon).
-2. In Google Tag Manager, go to **Templates**.
-3. Click **New**.
-4. Open the three-dot menu and click **Import**.
-5. Select the downloaded template file.
-6. Click **Save**.
-
-## Setup
-
-### 1. Create a Tag ID variable
-
-Sign in to the [Picked Dashboard](https://dashboard.picked.app) and copy your project Tag ID. Save it as a constant variable in GTM (e.g. `Picked Tag ID`).
-
-![Creating a Picked Tag ID variable in GTM](/gtm/gtm-variable.png)
-
-### 2. Create an ecommerce data variable
-
-Create a **Data Layer Variable** with the variable name set to `ecommerce`. This captures the GA4 Enhanced Ecommerce data layer.
-
-![GA4 Enhanced Ecommerce data layer variable](/gtm/gtm-ecommerce-variable.png)
-
-### 3. Create event triggers
-
-Add a trigger for each ecommerce event you want to track (e.g. `add_to_cart`, `purchase`, `view_item`).
-
-![Event triggers for ecommerce tracking](/gtm/gtm-triggers.png)
-
-### 4. Create tags
-
-Create a new tag for each event, selecting the **Picked Ecommerce** tag template. Assign the matching trigger and configure the options below.
-
-![Tags using the Picked Ecommerce template](/gtm/gtm-tags.png)
-
-## Configuration options
-
-| Option | Description |
-| --- | --- |
-| **Tag ID** | Your Picked project Tag ID. Find it in the [Picked Dashboard](https://dashboard.picked.app). |
-| **Event** | The ecommerce event to track (e.g. `add_to_cart`, `purchase`). |
-| **Send ecommerce data** | Enable this to send GA4 Enhanced Ecommerce data to Picked. Should be enabled for all ecommerce events. |
-| **GA4 Enhanced Ecommerce Data** | The GTM variable containing GA4 ecommerce data. Use the data layer variable created in step 2. |
-| **Additional data** | Optional GTM variable for sending extra metadata with the event. |
-
-![Picked Ecommerce tag configuration](/gtm/gtm-tag.png)

package/dist/docs/guides/build-a-personalized-page.mdx

@@ -1,143 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../../components/Screenshot'
-
-# Build a Personalized Page
-
-Build a personalized landing page with Picked: model it in the dashboard, publish it, and render it server-side in your app.
-
-## What you will build
-
-A standalone, SEO-critical landing page whose content lives in Picked's CMS and renders on your server. You model the page's shape once, fill it with content, publish it, then fetch and render it in React or Svelte. The lifecycle from authoring to a hydrated page:
-
-```
-Author (dashboard) -> Publish -> Delivery API (config + content)
-  -> serialize() on server -> Provider seeds client -> ExperienceSlot renders -> hydrate
-```
-
-## Model a page layout
-
-A [Page Layout](/content/layouts) defines the fields your page can hold.
-
-1. Open your workspace and click **Models** in the sidebar.
-2. Click **New Model** and choose **Page Layout**.
-3. Enter a name and a **Key**, for example `page-hero`. The Key is a unique, stable identifier you use in SDK code and API references.
-4. Add a few fields: a **Single-line text** field `title`, a **Markdown** field `body`, and an **Asset** field `image`.
-5. Save the layout.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/models"
-  alt="A page layout in the schema builder on the Picked dashboard"
-/>
-
-See [Page & Step Layouts](/content/layouts) for every field type.
-
-## Create and fill the page
-
-1. Click **Experiences** in the sidebar, then **New Experience**.
-2. Choose the **Page** type and pick your `page-hero` layout.
-3. On the **Properties** tab, fill in `title`, `body`, and `image`. A [Content Entry](/content/content-entries) is created and linked on first save.
-4. Fix any per-field validation errors.
-5. Publish the workspace to make the page live.
-
-See [Pages](/content/pages) for the full editor reference.
-
-## Fetch the config and content
-
-Your server fetches two things from the [Delivery API](/delivery-api): the project config (which experiences and steps exist) and the content for the matching experience.
-
-```bash
-# 1. Project config: find the steps and their content links
-curl https://api.picked.app/api/v1/projects/proj_123
-
-# 2. Experience content: the entry data backing the page
-curl https://api.picked.app/api/v1/projects/proj_123/experiences/exp_123/content
-```
-
-In practice you fetch the config, then let `serialize()` fetch the content for you. See [Project Config](/delivery-api/project-config) and [Experience Content](/delivery-api/experience-content).
-
-## Render server-side and hydrate
-
-On the server, create a per-request client, call `serialize()` to produce a snapshot, render your app, and embed the snapshot. On the client, seed from the snapshot and hydrate.
-
-```ts
-// server.ts
-import { createClient } from '@picked/client'
-import { serialize } from '@picked/client/server'
-
-const client = createClient(options)
-const snapshot = await serialize(client, {
-  projectConfig,
-  attributes: { location: { pathname: url.pathname } },
-})
-// Render your app, then embed `snapshot` in the HTML response.
-```
-
-Render `<ExperienceSlot name="page" />` inside the provider, and register the component the Page maps to (here, `CMSPage`):
-
-:::code-group
-
-```tsx [React]
-import type { CreateClientOptions } from '@picked/client'
-import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
-import { adaptReactComponent, ExperienceSlot, PickedProvider } from '@picked/react'
-import { reactFrameworkPlugin } from '@picked/react/plugins/framework'
-import { useStepContent } from '@picked/react/hooks'
-
-function CMSPage() {
-  const content = useStepContent()
-  const title = typeof content?.title === 'string' ? content.title : ''
-  return <h1>{title}</h1>
-}
-
-const options = {
-  projectId: 'proj_123',
-  components: { CMSPage: adaptReactComponent(CMSPage) },
-  plugins: [reactFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
-} satisfies CreateClientOptions
-
-export function Page({ snapshot }) {
-  return (
-    <PickedProvider options={options} snapshot={snapshot}>
-      <ExperienceSlot name="page" />
-    </PickedProvider>
-  )
-}
-```
-
-```svelte [Svelte]
-<script lang="ts">
-  import type { CreateClientOptions } from '@picked/client'
-  import { dynamicExperiencesPlugin } from '@picked/client/plugins/dynamic-experiences'
-  import { adaptSvelteComponent, ExperienceSlot, setPickedContext } from '@picked/svelte'
-  import { svelteFrameworkPlugin } from '@picked/svelte/plugins/framework'
-  import CMSPage from './CMSPage.svelte'
-
-  const { snapshot } = $props()
-
-  const options = {
-    projectId: 'proj_123',
-    components: { CMSPage: adaptSvelteComponent(CMSPage) },
-    plugins: [svelteFrameworkPlugin({ components: {} }), dynamicExperiencesPlugin()],
-  } satisfies CreateClientOptions
-
-  setPickedContext({ options, snapshot })
-</script>
-
-<ExperienceSlot name="page" />
-```
-
-:::
-
-The provider seeds synchronously, so the server HTML and the client's first paint match, then the SDK hydrates. See [Server-Side Rendering](/sdk/ssr) for the full reference.
-
-## Verify SEO
-
-Confirm the page is crawlable end to end:
-
-1. View the server response (for example with `curl` or your browser's view-source) and check the rendered HTML contains your `title` and `body`, not an empty shell.
-2. Confirm the content endpoint is reachable anonymously and returns your entry data.
-
-Published Delivery API responses are crawlable; preview URLs are disallowed. See [Preview, Caching & Crawling](/delivery-api/preview-caching-crawling).

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

@@ -1,80 +0,0 @@
----
-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.
-
-## Endpoint
-
-```
-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`). |
-
-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.
-
-## Allowed source domains
-
-The service only fetches from these hostnames:
-
-- `**.picked.app`
-
-A request whose `url` parameter resolves to any other hostname returns `400 Bad Request`.
-
-## Supported widths
-
-Device sizes, for responsive images that span the viewport width:
-
-```
-640, 750, 828, 1080, 1200, 1920, 2048, 3840
-```
-
-Image sizes, for fixed-size UI elements such as icons, avatars, and thumbnails:
-
-```
-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.
-
-## Supported qualities
-
-```
-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.
-
-## Responsive images
-
-Combine the endpoint with the standard `srcset` attribute to let browsers pick the right width per viewport:
-
-```html
-<img
-  src="https://img.picked-content.com/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=1080&q=75"
-  srcset="
-    https://img.picked-content.com/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=640&q=75 640w,
-    https://img.picked-content.com/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=1080&q=75 1080w,
-    https://img.picked-content.com/_next/image?url=https%3A%2F%2Fcdn.picked.app%2Fhero.png&w=1920&q=75 1920w
-  "
-  sizes="(max-width: 768px) 100vw, 720px"
-  alt="..."
-/>
-```
-
-## Caching
-
-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.
-
-## 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`.

package/dist/docs/mcp.md

@@ -1,120 +0,0 @@
----
-layout: docs
----
-
-# MCP server
-
-Manage your Picked workspace from AI coding tools using the Model Context Protocol (MCP).
-
-## Connecting
-
-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
-
-### Project configuration (.mcp.json)
-
-Add to your repository root. Works with Claude Code, Cursor, Windsurf, and other MCP-compatible tools.
-
-:::code-group
-
-```json [.mcp.json]
-{
-  "mcpServers": {
-    "picked": {
-      "type": "http",
-      "url": "https://api.picked.app/mcp"
-    }
-  }
-}
-```
-
-:::
-
-### Cursor
-
-Add to `.cursor/mcp.json` in your project root:
-
-```json
-{
-  "mcpServers": {
-    "picked": {
-      "type": "http",
-      "url": "https://api.picked.app/mcp"
-    }
-  }
-}
-```
-
-## Available 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) |
-
-### 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 |
-
-### Steps, fields, conditions, and actions
-
-| Tool                                | Description     |
-| ----------------------------------- | --------------- |
-| `get_step` / `list_steps`           | Read steps      |
-| `get_field` / `list_fields`         | Read fields     |
-| `get_condition` / `list_conditions` | Read conditions |
-| `get_action` / `list_actions`       | Read actions    |
-
-### Features
-
-| Tool             | Description                                        |
-| ---------------- | -------------------------------------------------- |
-| `create_feature` | Create a feature                                   |
-| `get_feature`    | Get feature details                                |
-| `list_features`  | List features                                      |
-| `update_feature` | Update name, description, enabled state, or weight |
-
-### Analytics
-
-| Tool             | Description                                                      |
-| ---------------- | ---------------------------------------------------------------- |
-| `query_pickedql` | Execute a PickedQL analytics query and return results as a table |
-
-Use `get_schema_info` with topic `pickedql` to see available tables, virtual functions, and dimension columns before writing queries.
-
-### Publishing
-
-| Tool                | Description                                    |
-| ------------------- | ---------------------------------------------- |
-| `get_preview_url`   | Generate a preview URL for unpublished changes |
-| `publish_workspace` | Publish 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"
-
-## 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.

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

@@ -1,145 +0,0 @@
----
-layout: docs
----
-
-# Data sources
-
-PickedQL provides four virtual tables (each optimized for different query patterns) plus three reference tables describing your Picked configuration.
-
-## `metrics` — Pre-aggregated daily data
-
-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.
-
-```sql
-SELECT device_category, control_users(), variant_users()
-FROM metrics
-WHERE project_id = 'your-project-id'
-GROUP BY device_category
-```
-
-## `events` — User-level event data
-
-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.
-
-```sql
-SELECT user_canonical_id, device_category
-FROM events
-WHERE project_id = 'your-project-id'
-  AND variant_type = 'Control'
-```
-
-## `features` — Feature flag analysis
-
-Best for querying user, session, and event counts per feature flag and bucket. Uses parameterized functions.
-
-```sql
-SELECT feature_users('homepage_test', 'control')
-FROM features
-WHERE project_id = 'your-project-id'
-```
-
-## `experience_journey` — Sankey-ready step transitions
-
-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.
-
-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.
-
-| Param (WHERE key) | Purpose |
-|---|---|
-| `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).
-
-```sql
--- "Overall user journey" sankey (card 4129 pattern) — forward window, target 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-30'
-```
-
-```sql
--- "Paths leading to target" sankey (card 2740 pattern) — backward window + top-N ranking
-SELECT source, target, users FROM experience_journey
-WHERE project_id             = 'your-project-id'
-  AND experience_id          = 'exp-123'
-  AND starting_step          = 'step-start'
-  AND targeting_step         = 'step-target'
-  AND num_nodes_before_target = 5
-  AND top_n_path             = 10
-```
-
-```sql
--- "Drop-off" sankey (card 2744 pattern) — omit targeting_step
-SELECT source, target, users FROM experience_journey
-WHERE project_id           = 'your-project-id'
-  AND experience_id        = 'exp-123'
-  AND starting_step        = 'step-start'
-  AND num_nodes_after_start = 10
-```
-
-```sql
--- Cohort sankey: only users who eventually converted (card 3961 pattern)
-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
-```
-
-Columns returned:
-
-| 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. |
-
-:::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.
-:::
-
-## Reference tables — `steps`, `experiences`, `projects`
-
-Reference tables describing your Picked configuration. They serve two roles:
-
-- **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.
-
-| Source | Tenant filter required |
-|---|---|
-| `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
-SELECT id, title FROM experiences WHERE project_id = 'your-project-id'
-
--- Direct query: load metadata for 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)
-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.