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

package/dist/docs/pickedql/dimensions.md

@@ -1,65 +0,0 @@
----
-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.
-
-## Available dimensions
-
-| Source | Columns |
-|---|---|
-| `dim_variant` | `variant_type`, `ab_feature_name`, `ab_feature_value` |
-| `dim_device` | `device_category`, `browser_name`, `browser_version`, `os_name`, `os_version`, `platform` |
-| `dim_geo` | `country_code`, `country_name`, `region`, `city` |
-| `dim_utm` | `utm_source`, `utm_medium`, `utm_campaign`, `utm_term`, `utm_content` |
-| `dim_product` | `product_name`, `product_category`, `product_page` |
-| `steps` | `step_title` |
-| `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:
-
-| Source | Tenant filter required |
-|---|---|
-| `steps`, `experiences` | `WHERE project_id = '<project_id>'` |
-| `projects` | `WHERE id = '<project_id>'` (the row's `id` 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.
-
-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`.
-
-```sql
--- Group events by experience and step name (auto-joins both `experiences` and `steps`)
-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:
-
-```sql
--- Dimension columns inside a CTE
-WITH per_step AS (
-  SELECT step_title, count(*) AS n
-  FROM events
-  WHERE project_id = 'your-project-id'
-  GROUP BY step_title
-)
-SELECT * FROM per_step ORDER BY n DESC
-
--- Dimension columns inside a nested SELECT
-SELECT step_title, n FROM (
-  SELECT step_title, count(*) AS n FROM events
-  WHERE project_id = 'your-project-id'
-  GROUP BY step_title
-) sub
-```
-
-## Native event columns
-
-These columns are available directly on `events` and require no join:
-
-`event_type`, `interaction_type`, `experience_id`, `step_id`, `event_id`, `user_canonical_id`, `session_id`, `client_local_date`, `is_purchase`, `is_cart_add`, `event_meta`.

package/dist/docs/pickedql/index.md

@@ -1,36 +0,0 @@
----
-layout: docs
----
-
-# PickedQL
-
-PickedQL is a SQL query language for querying your Picked analytics data. Write simple SQL using virtual tables and functions — PickedQL expands them into optimized queries with automatic joins and A/B test aggregations.
-
-## Quick start
-
-```sql
--- How many users are in the control vs variant group?
-SELECT control_users(), variant_users()
-FROM metrics
-WHERE project_id = 'your-project-id'
-```
-
-PickedQL handles table mapping and dimension joins automatically. You write concise, readable SQL — PickedQL does the rest.
-
-## How PickedQL works
-
-1. **Virtual table expansion**: Table names like `metrics` map to underlying data tables
-2. **Virtual function expansion**: Shorthand functions like `control_users()` expand to full aggregate expressions
-3. **Auto dimension joins**: References to dimension columns (like `device_category` or `country_code`) trigger automatic `LEFT JOIN` clauses — you never write joins yourself
-4. **Tenant isolation**: Every query must include a tenant filter in the `WHERE` clause — usually `project_id`, but `projects` uses `id` (the row's `id` IS the project id). PickedQL extracts the filter and verifies you have permission to access that project
-5. **SQL passthrough**: Standard SQL (including `CASE WHEN`, window functions, and subqueries) works alongside virtual functions
-
-## Best practices
-
-- **Use `metrics` for dashboards**: Pre-aggregated data is significantly faster than raw events for standard reporting
-- **Use `events` for deep dives**: Raw event-level data gives full flexibility for custom breakdowns and funnels
-- **Use `experience_journey` for sankey / funnel charts**: One line of SQL returns `source, target, users` — the 8-CTE scaffold (dedup, top-N path ranking, lagInFrame) is handled internally; pass parameters via `WHERE`
-- **Don't write JOINs**: PickedQL injects them automatically when you reference dimension columns
-- **Group by any dimension**: Add dimension columns to `SELECT` and `GROUP BY` freely — required joins are handled for you
-- **Reference table metadata for free**: Use `step_title`, `experience_title`, `project_name` directly in `events` queries — PickedQL auto-joins the `steps`, `experiences`, and `projects` reference tables
-

package/dist/docs/pickedql/schema.md

@@ -1,156 +0,0 @@
----
-layout: docs
----
-
-# Schema
-
-Column reference for each PickedQL data source.
-
-## `metrics`
-
-Pre-aggregated daily data. One row per unique combination of dimensions per day.
-
-| Column | Type | Description |
-|---|---|---|
-| `project_id` | String | Project identifier (required in `WHERE`) |
-| `project_local_date` | Date | Date in project timezone |
-| `experience_id` | String | Experience identifier |
-| `step_id` | String | Step identifier |
-| `event_type` | String | Event type (e.g., `page_view`, `click`) |
-| `interaction_type` | String | Interaction type (e.g., `Button Click`) |
-| `variant_type` | String | `Control`, `Variant`, or `Unknown` |
-| `device_category` | String | Device category (e.g., `Desktop`, `Mobile`) |
-| `country_code` | String | ISO country code |
-| `utm_source` | String | UTM source |
-| `utm_medium` | String | UTM medium |
-| `product_name` | String | Product name |
-| `product_category` | String | Product category |
-| `landing_page_url` | String | Landing page URL |
-
-:::note
-Aggregate columns (`users`, `sessions`, `events`, etc.) are not queried directly — use [virtual functions](./virtual-functions) instead.
-:::
-
-## `events`
-
-User-level event data. One row per event per user. Dimension columns are joined automatically when referenced.
-
-### Native columns
-
-| Column | Type | Description |
-|---|---|---|
-| `project_id` | String | Project identifier (required in `WHERE`) |
-| `event_id` | String | Unique event identifier |
-| `user_canonical_id` | String | Canonical user identifier |
-| `session_id` | String | Session identifier |
-| `experience_id` | String | Experience identifier |
-| `step_id` | String | Step identifier |
-| `event_type` | String | Event type (e.g., `page_view`, `click`) |
-| `interaction_type` | String | Interaction type (e.g., `Button Click`) |
-| `client_local_date` | Date | Date in client timezone |
-| `is_purchase` | UInt8 | `1` if checkout complete event |
-| `is_cart_add` | UInt8 | `1` if cart add event |
-| `is_first_session` | UInt8 | `1` if first session for this user |
-| `landing_page_url` | String | Landing page URL |
-| `features` | Map(String, String) | Feature flag assignments |
-| `feature_keys` | Map(String, String) | Feature key assignments |
-| `event_meta` | String | Event metadata |
-
-### Dimension columns (auto-joined)
-
-These columns are joined automatically when referenced — no `JOIN` syntax needed.
-
-| Column | Source | Description |
-|---|---|---|
-| `variant_type` | dim_variant | `Control`, `Variant`, or `Unknown` |
-| `ab_feature_name` | dim_variant | A/B feature name |
-| `ab_feature_value` | dim_variant | A/B feature value |
-| `device_category` | dim_device | Device category |
-| `browser_name` | dim_device | Browser name |
-| `browser_version` | dim_device | Browser version |
-| `os_name` | dim_device | Operating system name |
-| `os_version` | dim_device | Operating system version |
-| `platform` | dim_device | Platform |
-| `country_code` | dim_geo | ISO country code |
-| `country_name` | dim_geo | Country name |
-| `region` | dim_geo | Region |
-| `city` | dim_geo | City |
-| `utm_source` | dim_utm | UTM source |
-| `utm_medium` | dim_utm | UTM medium |
-| `utm_campaign` | dim_utm | UTM campaign |
-| `utm_term` | dim_utm | UTM term |
-| `utm_content` | dim_utm | UTM content |
-| `product_name` | dim_product | Product name |
-| `product_category` | dim_product | Product category |
-| `product_page` | dim_product | Product page |
-| `step_title` | steps | Step title (joined on `project_id` + `experience_id` + `step_id`) |
-| `experience_title` | experiences | Experience title (joined on `project_id` + `experience_id`) |
-| `project_name` | projects | Project name |
-| `project_timezone` | projects | Project timezone |
-
-## `steps`, `experiences`, `projects`
-
-Reference tables describing your Picked configuration. Auto-joined onto `events` when their analyst-facing columns are referenced; require a per-table tenant filter when queried directly.
-
-| Source | Real Columns | Analyst Columns (when referenced from `events`) | Tenant filter (when queried directly) |
-|---|---|---|---|
-| `steps` | `id`, `title`, `experience_id`, `project_id`, `organization_id` | `step_title` | `project_id = '…'` |
-| `experiences` | `id`, `title`, `project_id`, `organization_id` | `experience_title` | `project_id = '…'` |
-| `projects` | `id`, `name`, `timezone`, `organization_id` | `project_name`, `project_timezone` | `id = '<project_id>'` |
-
-When queried directly, use the real column names:
-
-```sql
--- List all experiences for a project
-SELECT id, title FROM experiences WHERE project_id = 'your-project-id'
-```
-
-When referenced from `events`, use the prefixed analyst names — joins are injected automatically:
-
-```sql
-SELECT experience_title, step_title, count(*)
-FROM events
-WHERE project_id = 'your-project-id'
-GROUP BY experience_title, step_title
-```
-
-## `features`
-
-The `features` table provides [parameterized virtual functions](./virtual-functions#feature-functions-features--events) for querying feature flag assignments:
-
-| Function | Description |
-|---|---|
-| `feature_users('name', 'bucket' [, 'key'])` | Unique users in a feature bucket |
-| `feature_sessions('name', 'bucket' [, 'key'])` | Unique sessions in a feature bucket |
-| `feature_events('name', 'bucket' [, 'key'])` | Unique events in a feature bucket |
-
-## `experience_journey`
-
-Aggregated step-transition edges for sankey / funnel charts. Parameters are supplied via the outer `WHERE` clause (PickedQL extracts them and substitutes into the underlying scaffold).
-
-### Columns
-
-| Column | Type | Description |
-|---|---|---|
-| `source` | String | Edge start, formatted as `NN. <step title>` (e.g., `001. Welcome screen`) |
-| `target` | String | Edge end, formatted as `NN. <step title>`. 
-| `users` | UInt64 | Distinct `user_canonical_id` count that traversed this edge. |
-
-### Parameters (via `WHERE`)
-
-| Key | Type | Required | Purpose |
-|---|---|---|---|
-| `project_id` | String | ✓ | Tenant filter. |
-| `experience_id` | String |  | Restrict to one `fact_events.experience_id`. |
-| `starting_step` | String |  | Anchor edges at first occurrence of this `step_id`. Defaults to each user's first step. |
-| `targeting_step` | String |  | Trim each user's window at their first occurrence of this `step_id`. Non-reachers still contribute their pre-cut journey. |
-| `num_nodes_after_start` | Integer |  | Forward window from start: keep steps where `seq_pos < start_seq + N` (card 4129 semantics). |
-| `num_nodes_before_target` | Integer |  | Backward window from target: keep steps where `seq_pos >= target_seq - N` (card 2740 semantics). Requires `targeting_step`. |
-| `top_n_path` | Integer |  | Keep only the top-N most-walked paths by user count. Defaults to no limit. |
-| `user_cohort_event` | String |  | Restrict to users who have at least one `fact_events` row with this `event_type`. Implemented as `user_canonical_id IN (SELECT DISTINCT user_canonical_id FROM fact_events WHERE event_type = '…')`. |
-| `client_local_date` | Date |  | Date range filter, pushed into the underlying scan. Supports `=`, `<`, `<=`, `>`, `>=`, `BETWEEN`. |
-| `event_timestamp` | DateTime64 |  | Server-side timestamp filter. Same operators as `client_local_date`. |
-
-When both window params are set, both predicates apply (intersection). Date filters combine via `AND` with the other params.
-
-See [data sources → experience_journey](./data-sources#experience_journey--sankey-ready-step-transitions) for usage examples.

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

@@ -1,204 +0,0 @@
----
-layout: docs
----
-
-# Virtual functions
-
-Virtual functions are shorthand for aggregate expressions. They are **table-aware** — the same function expands differently on `metrics` (pre-aggregated) vs `events` (user-level).
-
-## A/B test metrics
-
-| Function | Description |
-|---|---|
-| `control_users([condition])` | Unique users in the Control group, optionally filtered by a custom condition |
-| `variant_users([condition])` | Unique users in the Variant group, optionally filtered by a custom condition |
-| `all_users()` | All unique users |
-| `control_sessions([condition])` | Unique sessions in the Control group, optionally filtered by a custom condition |
-| `variant_sessions([condition])` | Unique sessions in the Variant group, optionally filtered by a custom condition |
-| `all_sessions()` | All unique sessions |
-
-### Custom filters on `events`
-
-On the `events` table, `control_*`/`variant_*` functions accept **one optional filter argument** to count only users/sessions matching the given expression, in addition to the implicit `variant_type` filter. The argument can be **positional** or **named** (`filter=`).
-
-The filter uses the same `column=value` syntax as conversion-rate conditions, with `AND`/`OR` operators and parentheses for grouping.
-
-```sql
--- Default: all Control users
-SELECT control_users() FROM events
-
--- Custom filter (positional)
-SELECT control_users('event_type=app_initialize') FROM events
-SELECT variant_users('event_type=app_initialize AND step_id=xxx') FROM events
-
--- AND/OR + parentheses
-SELECT control_users('event_type=app_initialize OR event_type=app_load') FROM events
-SELECT control_users('event_type=form_submit AND (step_id=lead-capture OR step_id=xxx)') FROM events
-
--- Sessions
-SELECT control_sessions('event_type=step_enter') FROM events
-SELECT variant_sessions('event_type=step_enter AND step_id=checkout') FROM events
-
--- Named form
-SELECT control_users(filter='event_type=app_initialize AND step_id=xxx') FROM events
-```
-
-:::note
-Custom filters are **not supported on `metrics`** (pre-aggregated data). On `metrics`, these functions ignore any arguments and use the default Control/Variant filter only.
-:::
-
-## Conversion metrics
-
-| Function | Description |
-|---|---|
-| `all_purchase_users()` | Users who completed a purchase |
-| `control_purchase_users()` | Control users who purchased (`metrics` only) |
-| `variant_purchase_users()` | Variant users who purchased (`metrics` only) |
-| `all_purchase_sessions()` | Sessions with a purchase (`metrics` only) |
-| `all_purchase_orders()` | Unique order count (`metrics` only) |
-| `all_cart_add_users()` | Users who added to cart |
-
-## Conversion rates
-
-| Function | Description |
-|---|---|
-| `control_conversion_rate([numerator [, denominator]])` | Conversion rate for Control. Defaults to purchase users / all users |
-| `variant_conversion_rate([numerator [, denominator]])` | Conversion rate for Variant. Same args as above |
-| `conversion_rate_uplift([numerator [, denominator]])` | Relative improvement: `(variant CR - control CR) / control CR`. Same args as above |
-
-### Custom conditions on `events`
-
-On the `events` table, conversion rate functions accept up to **2 optional arguments** to customize the numerator and denominator. Each argument can be either a **condition expression string** or a **nested virtual function call** (see below). Arguments can be **positional** or **named** (`numerator=`, `denominator=`).
-
-Each condition expression uses `column=value` with `AND`/`OR` operators and parentheses for grouping.
-
-```sql
--- Default: purchase users / all users
-SELECT control_conversion_rate() FROM events
-
--- Custom numerator, default denominator (all users)
-SELECT control_conversion_rate('event_type=form_submit_success') FROM events
-
--- AND/OR in conditions
-SELECT control_conversion_rate('event_type=checkout_complete OR event_type=order_create') FROM events
-SELECT control_conversion_rate('step_id=lead-capture AND event_type=form_submit_success') FROM events
-
--- Parentheses for grouping
-SELECT control_conversion_rate('event_type=form_submit AND (step_id=lead-capture OR step_id=xxx)') FROM events
-
--- Custom numerator AND denominator (positional)
-SELECT control_conversion_rate('event_type=form_submit', 'step_id=lead-capture') FROM events
-
--- Named arguments (explicit, any order)
-SELECT control_conversion_rate(numerator='event_type=form_submit', denominator='step_id=lead-capture') FROM events
-
--- Named: denominator only (numerator defaults to purchase)
-SELECT control_conversion_rate(denominator='step_id=lead-capture') FROM events
-
--- Uplift with named args
-SELECT conversion_rate_uplift(numerator='event_type=form_submit', denominator='step_id=lead-capture') FROM events
-```
-
-#### Nested virtual functions as numerator / denominator
-
-Instead of a condition string, you can pass a **virtual function call** as the numerator or denominator. The inner aggregate is substituted in place — no implicit `variant_type` filter is added on top of it (the nested function controls its own filter).
-
-This is the most flexible form when the numerator and denominator have different segments (e.g., Control users who fired event X over **all** users regardless of variant):
-
-```sql
--- (Control users who fired app_initialize) / (all users)
-SELECT control_conversion_rate(
-  control_users('event_type=app_initialize'),
-  all_users()
-) FROM events
-
--- Mix string and nested forms
-SELECT control_conversion_rate(
-  'event_type=form_submit',
-  all_users()
-) FROM events
-
--- Uplift with nested args
-SELECT conversion_rate_uplift(
-  control_users('event_type=app_initialize'),
-  all_users()
-) FROM events
-```
-
-:::note
-Custom conditions and nested virtual function args are **not supported on `metrics`** (pre-aggregated data). On `metrics`, these functions always use the default purchase / all users definition.
-:::
-
-## Visitor segmentation (`metrics` only)
-
-| Function | Description |
-|---|---|
-| `new_users()` | First-time visitors |
-| `returning_users()` | Returning visitors |
-| `new_sessions()` | Sessions from new visitors |
-| `returning_sessions()` | Sessions from returning visitors |
-
-## Funnel metrics (`events` only)
-
-:::note
-Funnel metrics are being continuously updated. Check back for new functions.
-:::
-
-| Function | Description |
-|---|---|
-| `step_enter_users()` | Users who entered a funnel step |
-| `step_enter_sessions()` | Sessions that entered a funnel step |
-
-## Cohort filters (`events` only)
-
-Predicate-shaped functions that emit a `user_canonical_id IN (SELECT … FROM events …)` subquery. Use in `WHERE` to restrict any analysis to users who have at least one event matching a custom condition.
-
-| Function | Description |
-|---|---|
-| `user_cohort_filter('<condition>')` | Restrict the query to users with ≥1 `events` row matching `<condition>` |
-| `user_cohort_filter(filter='<condition>')` | Same, named-arg form |
-
-`<condition>` uses the same `column=value [AND\|OR …]` shorthand as `control_users` / `variant_users`.
-
-```sql
--- Funnel scoped to users who eventually submitted lead capture
-SELECT all_users(), all_purchase_users()
-FROM events
-WHERE project_id = 'proj-abc'
-  AND user_cohort_filter('event_type=lead_capture')
-
--- Multi-condition cohort with OR-grouping
-SELECT all_sessions()
-FROM events
-WHERE project_id = 'proj-abc'
-  AND user_cohort_filter('event_type=signup OR event_type=trial_start')
-```
-
-The outer query MUST filter by a single `project_id` — the function bakes that tenant into the inner subquery so the cohort scan is scoped to your project, not the whole warehouse.
-
-## Feature functions (`features` / `events`)
-
-Parameterized functions that accept the feature name, bucket, and an optional feature key:
-
-| Function | Description |
-|---|---|
-| `feature_users('name', 'bucket' [, 'key'])` | Unique users in a feature bucket |
-| `feature_sessions('name', 'bucket' [, 'key'])` | Unique sessions in a feature bucket |
-| `feature_events('name', 'bucket' [, 'key'])` | Unique events in a feature bucket |
-
-```sql
--- Compare feature buckets
-SELECT
-  feature_users('homepage_test', 'control') AS control,
-  feature_users('homepage_test', 'variant') AS variant
-FROM features
-
--- With feature key filter
-SELECT feature_users('homepage_test', 'control', 'v1') FROM features
-```
-
-## Other (`metrics` only)
-
-| Function | Description |
-|---|---|
-| `event_count()` | Total event count (from pre-aggregation) |

package/dist/docs/projects.mdx

@@ -1,37 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../components/Screenshot'
-
-# Projects
-
-A project represents one website or app you want to instrument with Picked. Each project has its own set of experiences, entities, and configuration.
-
-<Screenshot
-  route="/{orgSlug}"
-  alt="The organization home page on the Picked dashboard, listing the projects in an organization"
-/>
-
-## Create a project
-
-You need an organization first. If you don't have one, create it when you sign up.
-
-1. Open your organization.
-2. Click **New Project**.
-3. Enter a name.
-4. Click **Create**.
-
-## Workspaces
-
-Each project contains one or more [Workspaces](/workspaces) for configuring and previewing experiences before publishing.
-
-## Project home
-
-When you open a project, you land on the project home page. It shows your SDK installation snippet and a getting-started checklist.
-
-Copy the snippet and add it to your site. This connects your site to the project and enables experience delivery. See [SDK Installation](/sdk) for setup details.
-
-## Project navigation
-
-The sidebar shows all sections available in your project: **Experiences**, **Fields**, **Steps**, **Actions**, **Conditions**, and more. Some sections appear only when enabled for your account.

package/dist/docs/reports.mdx

@@ -1,18 +0,0 @@
----
-layout: docs
----
-
-import { Screenshot } from '../../components/Screenshot'
-
-# Reports
-
-Reports show analytics data for your project. Track how visitors interact with your experiences and features.
-
-<Screenshot
-  route="/{orgSlug}/{projectId}/reports"
-  alt="The reports list for a project on the Picked dashboard"
-/>
-
-## View report data
-
-Open a report to see its analytics. Data updates as new visitor interactions are recorded.

package/dist/docs/sdk/actions.md

@@ -1,66 +0,0 @@
----
-layout: docs
----
-
-# Actions
-
-Register action handlers on the Picked client so the SDK can invoke them when an experience flow reaches an action node.
-
-## Registering actions
-
-Register actions when creating the Picked client. Each key in the `actions` object must match an action key defined in the dashboard:
-
-```ts
-import { createClient } from '@picked/client'
-
-const picked = createClient({
-  projectId: 'your-project-id',
-  actions: {
-    'track-signup': () => {
-      analytics.track('signup_completed')
-    },
-    'notify': (params) => {
-      sendNotification(params)
-    },
-  },
-})
-```
-
-Each action is a function that receives optional parameters and usually runs a side effect. When the flow reaches an action node, the SDK calls the matching function and branches on whether it succeeds or throws (see [Success and failure branching](#success-and-failure-branching)).
-
-## How actions work
-
-1. **Registration**: Actions are registered to the Picked client during initialization
-2. **Flow traversal**: When the SDK traverses the experience flow and reaches an action node, it looks up the action by its key
-3. **Execution**: The matching function is called and awaited. The SDK then continues to the next node based on the action's outcome
-4. **Non-blocking**: Actions don't interrupt the visitor's experience. The current step stays on screen while an async action runs
-
-## Success and failure branching
-
-An action node can have separate **success** and **failure** branches. The SDK selects the branch from the action's outcome:
-
-- **Failure** — the action throws (or its promise rejects). The flow follows the failure (`onFail`) branch.
-- **Success** — the action resolves to any value (`void`, `true`, `false`, or a string). A resolved `false` is a valid response, not a failure. The flow follows the success (`onSuccess`) branch.
-
-Reserve the failure branch for genuine errors — throw on the failure case, since a returned value never routes to `onFail`:
-
-```ts
-'check-eligibility': async () => {
-  const response = await fetch('/api/eligibility')
-  // Throw only when the request itself fails — that takes the failure branch.
-  if (!response.ok) throw new Error('Eligibility request failed')
-}
-```
-
-A valid negative result is not a failure. An API that returns `200` with a "no" (for example `{ serviced: false }`) should record that value as a response and branch on it with a condition, rather than throw:
-
-```ts
-'check-serviced-area': async ({ client, responses }) => {
-  const postcode = responses.find((r) => r.fieldKey === 'postcode')?.value
-  const { serviced } = await fetch(`/api/serviced?postcode=${postcode}`).then((r) => r.json())
-  // Commit the outcome as a response; a downstream condition routes the flow.
-  client.responses.register('is-serviced', serviced)
-}
-```
-
-If an action node has only a single plain connection (no explicit success or failure branch), the flow continues through it on either outcome.

package/dist/docs/sdk/content-security-policy.md

@@ -1,32 +0,0 @@
----
-layout: docs
----
-
-# Content Security Policy
-
-The Picked SDK loads resources from the following domains. Add each to the matching CSP directive.
-
-## Required domains
-
-| Domain | Directive | Purpose |
-| --- | --- | --- |
-| `api.picked.app` | `connect-src` | API requests, project configuration, experiences, session tracking |
-| `evnts.pckd.dev` | `connect-src` | Analytics event collection (Snowplow) |
-| `img.picked-content.com` | `img-src` | Optimised images served via the [image optimisation service](../image-optimisation-service.md) |
-
-## Configuration
-
-As an HTTP header:
-
-```
-Content-Security-Policy: connect-src 'self' https://api.picked.app https://evnts.pckd.dev; img-src 'self' https://img.picked-content.com;
-```
-
-Or as a `<meta>` tag:
-
-```html
-<meta
-  http-equiv="Content-Security-Policy"
-  content="connect-src 'self' https://api.picked.app https://evnts.pckd.dev; img-src 'self' https://img.picked-content.com;"
-/>
-```

package/dist/docs/sdk/experiences.md

@@ -1,46 +0,0 @@
----
-layout: docs
----
-
-# Experiences
-
-Define experiences in code with `createExperience()`, or load them from the dashboard at runtime with the [Dynamic Experiences Plugin](./plugins/dynamic-experiences).
-
-The execution flow below targets a DOM selector and renders into it. A Page experience instead renders through a named slot: target it to `.picked-slot-<name>` and render `<ExperienceSlot name="<name>" />` on your server. Use the slot path for SEO-critical, server-rendered Pages; use the selector path for browser-rendered Flows. See [Server-Side Rendering](/sdk/ssr) and [Slots & Placements](/sdk/ssr/slots-and-placements).
-
-## Creating experiences
-
-```ts
-import { createExperience } from '@picked/client/plugins/create-experience'
-import { adaptSvelteComponent } from '@picked/svelte'
-import appCss from '../app.css?inline'
-
-export const productPageExperience = createExperience({
-  id: 'product-page-experience',
-  name: 'Product Page Experience',
-  condition: {
-    '==': [
-      { var: 'location.pathname' },
-      '/product/',
-    ],
-  },
-  targets: [{ selector: 'body', placement: 'after' }],
-  component: adaptSvelteComponent(
-    import('../ui/ProductPageExperience.svelte'),
-    { css: [appCss] },
-  ),
-})
-```
-
-Register experiences using the [Create Experience Plugin](./plugins/create-experience) for code-defined experiences, or the [Dynamic Experiences Plugin](./plugins/dynamic-experiences) to fetch and manage them from the dashboard at runtime.
-
-## How experiences work
-
-When an experience is registered, the SDK follows this execution flow:
-
-1. **Registration**: Experiences are registered to the Picked client using [createExperiencePlugin](./plugins/create-experience) for code-defined experiences, or [dynamicExperiencesPlugin](./plugins/dynamic-experiences) for dashboard-managed experiences
-2. **Condition evaluation**: The SDK evaluates the experience's `condition` using the logic engine to determine if it should be shown
-3. **Target resolution**: The SDK searches the DOM for elements matching the `targets` selectors (e.g., `body`, `.product-page`, `#checkout`)
-4. **Initialization**: If the condition evaluates to `true` and at least one target element exists, the experience is initialized
-5. **Component rendering**: The experience's component is rendered and injected into the DOM at the specified target location and placement (before, after, append, prepend, or replace)
-6. **Flow execution**: If the experience contains steps, fields, and conditionals, users can progress through the multi-step flow with validation and branching logic