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

package/dist/docs/explanation/workspaces-and-versions.md

@@ -0,0 +1,71 @@
+---
+type: explanation
+layout: docs
+---
+
+# About workspaces and versions
+
+Why can you not edit what your visitors see? Because Picked keeps two things separate on
+purpose: the work in progress, and the thing that it serves.
+
+## The two states
+
+A **workspace** holds your changes. Edit a flow, a feature flag, a step, a field, an
+action, or a condition, and the change stays in the workspace. No visitor sees it.
+
+A **version** is what your visitors get. When you publish, Picked takes the current
+workspace and makes an immutable snapshot of it. A project serves exactly one version at a
+time, the live one.
+
+Everything else follows from that split.
+
+## Why the snapshot is immutable
+
+A published version cannot change. That is what makes a roll-back safe. When you restore
+an earlier version, Picked moves the live pointer of the project and changes no data. The
+version that you restore is the exact version that was live before, and not a copy that
+Picked builds again.
+
+It is also what lets your draft continue. When you publish, your workspace stays
+editable, and a roll-back discards no draft. The two move at their own speed.
+
+## The three workspace states
+
+- **Live** — the workspace whose snapshot the SDK serves. Each project has exactly one.
+- **Draft** — a workspace that no visitor sees. Edit it, see a preview of it, publish it.
+- **Archived** — a draft that you put to one side. It is still editable, but it is out of
+  the default list.
+
+Picked keeps these two operations separate on purpose. Archive a draft when you are not
+certain about it. You cannot reverse a delete, but you can always unarchive.
+
+## Why the publish modal shows a diff
+
+It is the one step in the dashboard that you cannot take back. It is therefore the one
+place that shows you exactly what changes. The modal compares the current workspace
+against the last published snapshot. It puts the changes into groups, and marks each row
+added, removed, or modified.
+
+The diff also carries a warning that a plain list of changes cannot give you. Some changes
+break other records. Remove a field while steps still point at it, and those steps
+now have an error. The preview shows that above the diff, before you publish and not after.
+
+The first publish of a workspace has no earlier snapshot to compare against, so the modal
+shows the contents instead of a diff.
+
+## A preview does not reach production
+
+A preview sends the workspace state to the SDK in the query parameters. Your unpublished
+workspace therefore applies to your browser and to nothing else. The visitors on your live
+site see no change.
+
+One result of this matters. In a preview the SDK stores a feature flag decision in session
+storage and not in local storage. A preview allocation is therefore disposable, and it can
+differ from a production one. See
+[About feature flag allocation](/explanation/feature-flag-allocation).
+
+## Related
+
+- [About how Picked works](/explanation/how-picked-works) — what a publish feeds.
+- [Workspaces](/reference/dashboard/workspaces) — the states and the settings.
+- [Publish history](/reference/dashboard/workspace-versioning) — the version list.

package/dist/docs/how-to/add-a-step-field-or-action.md

@@ -0,0 +1,43 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to add a step, a field, an action, or a condition
+
+This guide shows you how to create the parts that a flow is built from. All four follow
+the same shape, and all four belong to the project: you can use one in more than one flow.
+
+## Steps
+
+1. Open a flow. The library is on the left of the flow builder.
+2. Find the **Steps**, **Fields**, **Actions**, or **Conditions** section in it.
+3. Click the **+** next to that section.
+4. Enter a name. The dashboard makes the key from it.
+5. Click the **Create** button for that kind: **Create step**, **Create field**,
+   **Create action**, **Create condition**.
+
+The flow builder opens again, and the new one is in the library.
+
+**Fields** also has its own sidebar entry, so you can make a field without a flow. A step,
+an action, and a condition belong to a flow, and the library is the only way to reach
+them.
+
+The key is the identifier that your application uses. You set it one time, and you cannot
+change it later. Your visitors never see a name or a key.
+
+## What each one needs after that
+
+| Kind | Set this next |
+| --- | --- |
+| Step | A **Layout**, such as `card`, `modal`, or `fullscreen`. |
+| Field | A **Label**, a type, and any validation rule. |
+| Action | Nothing in the dashboard. Register the handler in your code. |
+| Condition | The rule, in the **Logic** section of the inspector. |
+
+## Related
+
+- [How to build a flow](/how-to/build-a-flow) — put it on the canvas.
+- [How to write a condition](/how-to/write-a-condition)
+- [How to register an action handler](/how-to/register-an-action-handler)
+- [How to reuse a step, a field, or an action](/how-to/reuse-a-step-field-or-action)

package/dist/docs/{pickedql/examples.md → how-to/analytics/index.md}

@@ -1,8 +1,16 @@
 ---
+type: how-to
 layout: docs
 ---
 
-# Example queries
+# How to run an analytics query
+
+This guide gives you a query for each common analytics question. Copy one, put your own
+project ID in the `WHERE` clause, and run it.
+
+Every query must carry a tenant filter. See
+[About PickedQL](/explanation/how-pickedql-works) for why, and
+[Data sources](/reference/pickedql/data-sources) for every table.
 
 ## Daily A/B test trend
 
@@ -51,7 +59,9 @@ ORDER BY project_local_date
 
 ## Custom conversion rate definition
 
-Override the default purchase conversion with your own numerator and denominator. Useful when conversion is defined by a form submission, lead capture, or any custom event.
+Override the default conversion, which counts a `purchase` event, with your own
+numerator and denominator. Use this when a form submission, a lead capture, or
+another event of your own defines a conversion.
 
 ```sql
 -- Lead capture conversion: form submissions / lead-capture step entries
@@ -75,7 +85,7 @@ ORDER BY project_local_date
 You can also combine multiple events with `OR` and group with parentheses:
 
 ```sql
--- Either checkout_complete or order_create counts as a conversion
+-- A `checkout_complete` event or an `order_create` event counts as a conversion.
 SELECT
   control_conversion_rate(
     'event_type=checkout_complete OR event_type=order_create'
@@ -87,12 +97,15 @@ FROM events
 WHERE project_id = '{{ your project ID }}'
 ```
 
-## Custom segment with `control_users` / `variant_users`
+## Your own segment with `control_users` and `variant_users`
 
-On `events`, `control_users` / `variant_users` / `control_sessions` / `variant_sessions` accept an optional filter string to count only users/sessions matching the given expression in addition to the implicit `variant_type` filter.
+On `events`, four functions take an optional filter string: `control_users`,
+`variant_users`, `control_sessions`, and `variant_sessions`. The filter counts only a
+user or a session that matches your expression. It applies together with the
+`variant_type` filter that PickedQL adds.
 
 ```sql
--- Control users who fired app_initialize, broken down by step
+-- The control users who fired an `app_initialize` event, by step.
 SELECT
   step_id,
   control_users('event_type=app_initialize')                      AS control_initialized,
@@ -113,10 +126,13 @@ WHERE project_id = '{{ your project ID }}'
 
 ## Conversion rate from nested virtual functions
 
-When numerator and denominator come from different segments — e.g., Control users who fired a custom event divided by **all** users (not just Control) — pass virtual function calls directly as conversion-rate args:
+The numerator and the denominator can come from different segments. An example is the
+control users who fired an event of your own, divided by **all** users and not by the
+control users alone. For that, pass a virtual function call directly as an argument
+of the conversion rate:
 
 ```sql
--- (Control users who fired app_initialize) / (all users, regardless of variant)
+-- The control users who fired `app_initialize`, over all users of every variant.
 SELECT
   control_conversion_rate(
     control_users('event_type=app_initialize'),
@@ -188,9 +204,9 @@ GROUP BY utm_source
 
 | utm_source | users  | purchasers |
 | ---------- | ------ | ---------- |
-| meta       | 12031  | 101        |
-| fb         | 3656   | 31         |
-| an         | 100366 | 299        |
+| `meta`       | 12031  | 101        |
+| `fb`         | 3656   | 31         |
+| `an`         | 100366 | 299        |
 
 ## Step funnel for variant users
 
@@ -211,18 +227,19 @@ ORDER BY variant DESC
 
 | step_id                        | variant |
 | ------------------------------ | ------- |
-| who-are-you-protecting-step    | 1093    |
-| about-yourself-step            | 533     |
-| date-of-birth-step             | 435     |
-| employment-status-step         | 408     |
-| nicotine-usage-step            | 407     |
-| coverage-motivation-step       | 405     |
-| lead-capture-step              | 398     |
+| `who-are-you-protecting-step`    | 1093    |
+| `about-yourself-step`            | 533     |
+| `date-of-birth-step`             | 435     |
+| `employment-status-step`         | 408     |
+| `nicotine-usage-step`            | 407     |
+| `coverage-motivation-step`       | 405     |
+| `lead-capture-step`              | 398     |
 
 
 ## Sankey — overall user journey
 
-Forward window from the starting step. Non-reachers of `targeting_step` still contribute edges up to `num_nodes_after_start`. Mirrors dashboard 1156 card 4129's semantics.
+A forward window from the starting step. A user who never reaches `targeting_step`
+still gives edges, up to `num_nodes_after_start`.
 
 ```sql
 SELECT source, target, users FROM experience_journey
@@ -236,13 +253,14 @@ WHERE project_id            = '{{ your project ID }}'
 
 | source                    | target                    | users |
 | ------------------------- | ------------------------- | ----- |
-| 001. step-start           | 002. step-questionnaire-1 | 182   |
-| 002. step-questionnaire-1 | 003. step-quote           | 144   |
-| 003. step-quote           | 004. step-target          | 121   |
+| `001. step-start`           | `002. step-questionnaire-1` | 182   |
+| `002. step-questionnaire-1` | `003. step-quote`           | 144   |
+| `003. step-quote`           | `004. step-target`          | 121   |
 
-## Sankey — top paths leading to a target step
+## Sankey — the top paths to a target step
 
-Backward window anchored at the target, plus top-N path ranking. Mirrors dashboard 1156 card 3961 / dashboard 991 card 2740 semantics.
+A backward window anchored at the target. It also ranks the paths and keeps the ones
+with the most users.
 
 ```sql
 SELECT source, target, users FROM experience_journey
@@ -256,7 +274,7 @@ WHERE project_id              = '{{ your project ID }}'
 
 ## Sankey — drop-off view
 
-Starts at `starting_step` and emits every consecutive transition until `num_nodes_after_start` steps later (no target). Mirrors card 2744.
+Starts at `starting_step` and emits every consecutive transition until `num_nodes_after_start` steps later (no target).
 
 ```sql
 SELECT source, target, users FROM experience_journey
@@ -284,6 +302,13 @@ WHERE project_id = '{{ your project ID }}'
 
 | device_category | user_canonical_id                    |
 | --------------- | ------------------------------------ |
-| Mobile          | 019cc336-5a6a-7c32-b638-cdcc983b3e70 |
-| Mobile          | 019cc336-5a6a-7d8f-994c-69bc28e5f550 |
-| Mobile          | 019cc80f-503c-7181-b2c6-986b1f76d496 |
+| Mobile          | `019cc336-5a6a-7c32-b638-cdcc983b3e70` |
+| Mobile          | `019cc336-5a6a-7d8f-994c-69bc28e5f550` |
+| Mobile          | `019cc80f-503c-7181-b2c6-986b1f76d496` |
+
+## Related
+
+- [About PickedQL](/explanation/how-pickedql-works) — what the layer expands for you.
+- [Virtual functions](/reference/pickedql/virtual-functions) — every function.
+- [Dimensions](/reference/pickedql/dimensions) — every dimension column.
+- [Reports](/reference/dashboard/reports) — the same data as an embedded dashboard.

package/dist/docs/how-to/archive-or-delete-a-workspace.md

@@ -0,0 +1,46 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to archive or delete a workspace
+
+This guide shows you how to take a draft workspace out of use. Archive it when you want
+to keep it. Delete it only when you are certain, because you cannot reverse a delete.
+
+You cannot archive or delete a live workspace. Make a different workspace live first.
+
+## Archive a workspace
+
+1. Open the workspace settings page.
+2. Click **Archive workspace** in the page header.
+3. Confirm in the modal.
+
+The workspace leaves the default list. It stays editable.
+
+## Unarchive a workspace
+
+1. Open the workspace settings page.
+2. Click **Unarchive workspace** in the page header.
+
+## Delete a workspace
+
+1. Open the workspace settings page.
+2. Click **Delete workspace**.
+3. Confirm in the modal.
+
+Picked removes the workspace, and everything in it, permanently.
+
+## Rename a workspace
+
+1. Open the workspace settings page.
+2. Change the **Workspace name** field.
+3. Click **Save changes**.
+
+A name is unique inside a project. The dashboard rejects a duplicate name.
+
+## Related
+
+- [About workspaces and versions](/explanation/workspaces-and-versions) — why Picked keeps
+  these two operations separate.
+- [Workspaces](/reference/dashboard/workspaces) — the settings reference.

package/dist/docs/how-to/authenticate-with-a-magic-link.md

@@ -0,0 +1,40 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to authenticate with a magic link
+
+This guide shows you how to sign a user in through an email address, with no password.
+
+## 1. Send the link
+
+```graphql
+mutation {
+  magicLinkSend(input: {
+    email: "user@example.com"
+    redirectUrl: "https://app.example.com/auth/verify"
+  }) {
+    success
+  }
+}
+```
+
+The user receives an email, and the link in it holds a token.
+
+## 2. Verify the token
+
+```graphql
+mutation {
+  magicLinkVerify(input: {
+    email: "user@example.com"
+    token: "token-from-magic-link"
+  }) {
+    session { accessToken refreshToken }
+  }
+}
+```
+
+## Related
+
+- [Authentication](/reference/management-api/authentication) — every mutation.

package/dist/docs/how-to/authenticate-with-a-password.md

@@ -0,0 +1,51 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to authenticate with a password
+
+This guide shows you how to get an access token from an email address and a password.
+
+## 1. Create a session
+
+```graphql
+mutation {
+  sessionCreate(input: {
+    email: "user@example.com"
+    password: "secure-password"
+  }) {
+    session { accessToken refreshToken expiresAt }
+    requiresMfa
+  }
+}
+```
+
+When `requiresMfa` is `true`, complete the challenge first. See
+[How to set up MFA](/how-to/set-up-mfa).
+
+## 2. Send the token
+
+```
+Authorization: Bearer <accessToken>
+```
+
+## 3. Refresh before it expires
+
+The `expiresAt` field gives the time at which the access token expires.
+
+```graphql
+mutation {
+  sessionRefresh(input: { refreshToken: "v1.refresh-token..." }) {
+    session { accessToken refreshToken expiresAt }
+  }
+}
+```
+
+The API invalidates the earlier refresh token. This mutation needs no `Authorization`
+header.
+
+## Related
+
+- [Authentication](/reference/management-api/authentication) — every mutation.
+- [Your first API call](/tutorials/first-api-call).

package/dist/docs/how-to/authenticate-with-an-api-key.md

@@ -0,0 +1,51 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to authenticate with an API key
+
+This guide shows you how to authenticate a server-to-server integration. An API key gives
+access for a long time, inside a set of scopes.
+
+## 1. Create the key
+
+Only a user with a session can create a key. Another API key cannot.
+
+```graphql
+mutation {
+  apiKeyCreate(input: {
+    organizationId: "org-id"
+    name: "CI/CD Pipeline Key"
+    projectId: "project-id"
+    scopes: [ORGANIZATION_READ, ORGANIZATION_PROJECTS_READ]
+  }) {
+    apiKey
+  }
+}
+```
+
+The response holds the full key one time only. Keep it in a secure place.
+
+The scopes that you ask for must all be scopes of the user who creates the key.
+
+## 2. Send the key
+
+```
+x-api-key: pk_live_abc123...
+```
+
+## 3. Revoke the key
+
+```graphql
+mutation {
+  apiKeyRevoke(input: { keyId: "key-id", organizationId: "org-id" })
+}
+```
+
+## Related
+
+- [Authorization and scopes](/reference/management-api/authorization-and-scopes) — every
+  scope.
+- [How to create and revoke an API key](/how-to/create-and-revoke-an-api-key) — the
+  dashboard path.

package/dist/docs/how-to/authenticate-with-oauth.md

@@ -0,0 +1,40 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to authenticate with OAuth
+
+This guide shows you how to sign a user in through Google.
+
+## 1. Get the authorization URL
+
+```graphql
+mutation {
+  oauthAuthorize(input: {
+    provider: GOOGLE
+    redirectUrl: "https://app.example.com/auth/callback"
+    scopes: ["openid", "email", "profile"]
+  }) {
+    url
+  }
+}
+```
+
+## 2. Send the user to that URL
+
+Google authenticates the user and sends them back with a `code` parameter.
+
+## 3. Exchange the code
+
+```graphql
+mutation {
+  oauthCallback(input: { provider: GOOGLE, code: "auth-code-from-google" }) {
+    session { accessToken refreshToken expiresAt }
+  }
+}
+```
+
+## Related
+
+- [Authentication](/reference/management-api/authentication) — every mutation.

package/dist/docs/how-to/build-a-flow.md

@@ -0,0 +1,83 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to build a flow
+
+This guide shows you how to put a flow together on the canvas. You need an experience
+first. See [How to create an experience](/how-to/create-an-experience).
+
+## Add nodes
+
+Drag a step, an action, or a condition from the library onto the canvas. A new
+node appears where you drop it.
+
+You can also drop a block directly onto an arrow that is there already. The flow
+builder puts the node into the line. The first arrow splits into two arrows, with the
+new node between them. A **+** indicator appears when you hold the pointer over a
+valid arrow.
+
+## Connect nodes
+
+Click the output handle of a node, on the right side. Drag to the input handle of
+another node, on the left side. An arrow then joins the two nodes.
+
+The flow follows the arrows from left to right, and it starts at the origin. Every
+node after the origin is part of the experience flow.
+
+## Branch with conditions
+
+Connect the origin, or any other node, to a condition node. The condition evaluates
+its rule and sends the flow down one of two paths.
+
+Connect the green handle, for a true result, to the nodes that must run when the
+condition holds. Connect the red handle, for a false result, to the other path. Each
+path can lead to more steps, more actions, and more conditions.
+
+## Assign fields to steps
+
+Drag a field from the library onto a step node and drop it. That step then
+holds the field.
+
+You can assign more than one field to one step. The step node gives the number of
+assigned fields. To see which fields it holds, choose the step. Then read the **Fields**
+section in the inspector.
+
+## Choose nodes
+
+Click a node to choose it. Its inspector opens in the right panel.
+
+Drag on empty canvas to choose every node inside a rectangle. Press `Cmd/Ctrl+A` to
+choose every node.
+
+When you choose more than one node, the inspector gives a count and a list in groups.
+Click an item in that list to open its inspector.
+
+## Move nodes
+
+Drag a node to move it. Each node snaps to the grid.
+
+Use the arrow keys to move a node a small distance. Hold `Shift` to move it further.
+
+## Delete nodes
+
+Choose one or more nodes. Press `Delete` or `Backspace`. The flow builder removes
+those nodes and every arrow that joins them.
+
+## Duplicate nodes
+
+Choose one or more nodes. Press `Cmd/Ctrl+D`. A copy of each node appears next to the
+first one.
+
+## Undo and redo
+
+Press `Cmd/Ctrl+Z` to undo. Press `Cmd/Ctrl+Shift+Z` to redo. The undo stack records
+each node that you add, each node that you delete, each connection, and each move.
+
+## Related
+
+- [Canvas](/reference/dashboard/flow-builder/canvas) — the panels and the view controls.
+- [Nodes](/reference/dashboard/flow-builder/nodes) — every node type.
+- [Keyboard shortcuts](/reference/dashboard/flow-builder/keyboard-shortcuts)
+- [About how Picked works](/explanation/how-picked-works) — why a flow is a graph.

package/dist/docs/how-to/connect-the-mcp-server.md

@@ -0,0 +1,38 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to connect the MCP server
+
+This guide shows you how to control your Picked workspace from an AI tool that writes
+code. The server URL is `https://api.picked.app/mcp`.
+
+## Claude Desktop
+
+1. Open **Settings > Connectors > Add custom connector**.
+2. Set **Name** to `Picked`.
+3. Set **URL** to `https://api.picked.app/mcp`.
+4. Click **Connect**.
+5. Answer the authorization prompt.
+
+## Claude Code, Cursor, Windsurf, and others
+
+Add `.mcp.json` to the root of your repository:
+
+```json
+{
+  "mcpServers": {
+    "picked": {
+      "type": "http",
+      "url": "https://api.picked.app/mcp"
+    }
+  }
+}
+```
+
+Cursor reads the same content from `.cursor/mcp.json`.
+
+## Related
+
+- [MCP server](/reference/tools/mcp) — every tool that the server gives you.

package/dist/docs/how-to/create-a-project.md

@@ -0,0 +1,29 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to create a project
+
+This guide shows you how to add a project. A project is one site or one application, and
+it holds its own experiences, content, and options.
+
+## Steps
+
+1. Open your organization.
+2. Click **New project**.
+3. Enter a name.
+4. Click **Create project**.
+
+The project home page opens. It shows your SDK snippet and the setup tasks that are still
+open.
+
+## Next
+
+Copy the snippet and add it to your site. See
+[How to install the SDK](/how-to/install-the-sdk).
+
+## Related
+
+- [Projects](/reference/dashboard/projects) — the project surface.
+- [Add Picked to your application](/tutorials/first-experience) — the whole path.