@picked/client 0.0.1-dev.1785826066660 → 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
 
@@ -231,8 +239,7 @@ ORDER BY variant DESC
 ## Sankey — overall user journey
 
 A forward window from the starting step. A user who never reaches `targeting_step`
-still gives edges, up to `num_nodes_after_start`. This does what card 4129 on
-dashboard 1156 does.
+still gives edges, up to `num_nodes_after_start`.
 
 ```sql
 SELECT source, target, users FROM experience_journey
@@ -253,8 +260,7 @@ WHERE project_id            = '{{ your project ID }}'
 ## Sankey — the top paths to a target step
 
 A backward window anchored at the target. It also ranks the paths and keeps the ones
-with the most users. This does what card 3961 on dashboard 1156 and card 2740 on
-dashboard 991 do.
+with the most users.
 
 ```sql
 SELECT source, target, users FROM experience_journey
@@ -268,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
@@ -299,3 +305,10 @@ WHERE project_id = '{{ your project ID }}'
 | 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/{flow-builder/building-flows.md → how-to/build-a-flow.md}

@@ -1,15 +1,16 @@
 ---
+type: how-to
 layout: docs
 ---
 
-# Build flows
+# How to build a flow
 
-To build a flow, drag a block onto the canvas. Connect your nodes with arrows. Then
-set the options of each node in the inspector.
+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 entity browser onto the canvas. A new
+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
@@ -36,12 +37,12 @@ path can lead to more steps, more actions, and more conditions.
 
 ## Assign fields to steps
 
-Drag a field from the entity browser onto a step node and drop it. That step then
+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
-**Assigned Fields** section in the inspector.
+assigned fields. To see which fields it holds, choose the step. Then read the **Fields**
+section in the inspector.
 
 ## Choose nodes
 
@@ -74,6 +75,9 @@ first one.
 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
 
-[Overview](/flow-builder/overview) · [Nodes](/flow-builder/nodes) · **Build Flows** · [Keyboard Shortcuts](/flow-builder/keyboard-shortcuts) · [Condition Builder](/flow-builder/condition-builder)
+- [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.

package/dist/docs/how-to/create-an-experience.md

@@ -0,0 +1,42 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to create an experience
+
+An experience is a Flow or a Page. This guide adds a **Flow**: the interactive kind, of
+more than one step, which the browser renders. A **Page** is the standalone kind that your
+server renders for a search engine, and
+[How to fill and publish a page](/how-to/fill-and-publish-a-page) covers it.
+
+[About pages and flows](/explanation/pages-and-flows) sets out the difference, and which
+kind a piece of work needs.
+
+## Steps
+
+1. Open your project.
+2. Click **Flows** in the sidebar. The experiences list opens.
+3. Click **New experience**.
+4. Enter a name.
+5. Leave **Type** on the **Flow** option.
+6. Open **Advanced**.
+7. Enter a component name. It must match a component that you register in your
+   application.
+8. Click **Create flow**.
+
+The flow editor opens with an empty canvas.
+
+## Set the options
+
+Click the canvas background to open the experience inspector.
+
+- **Condition** — the experience starts only for a visitor who matches it. Keep it blank
+  to start for every visitor.
+- **Initialize Open** — the experience opens by itself when the page loads.
+
+## Related
+
+- [How to build a flow](/how-to/build-a-flow) — add your first node.
+- [About pages and flows](/explanation/pages-and-flows) — Page or Flow.
+- [Experiences](/reference/dashboard/experiences) — every option.

package/dist/docs/how-to/create-and-revoke-an-api-key.md

@@ -0,0 +1,37 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to create and revoke an API key
+
+This guide shows you how to give your code access to the Picked API. Use a key for a
+server-side integration or for a CI/CD workflow.
+
+## Create a key
+
+1. Open your organization.
+2. Click **API Keys**.
+3. Click **Create API Key**.
+4. Enter a **Name**, such as `Production key`.
+5. Set **Project** to one project. The default, **All projects**, gives the key every
+   project.
+6. Choose the **Permissions** that your integration needs.
+7. Click **Create API Key**.
+
+:::warning
+Copy the key immediately. The dashboard does not show it again.
+:::
+
+## Revoke a key
+
+1. Open the API keys list.
+2. Click **Revoke** next to the key.
+3. Click **Revoke Key** to confirm.
+
+Picked invalidates the key immediately. No later request can use it.
+
+## Related
+
+- [API keys](/reference/dashboard/api-keys) — the scopes.
+- [Authentication](/reference/management-api/authentication) — how to send the key.

package/dist/docs/how-to/debug-with-the-chrome-extension.md

@@ -0,0 +1,57 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to debug with the Chrome extension
+
+This guide shows you how to add a Picked panel to Chrome DevTools and check your
+integration on any page that runs the SDK.
+
+## 1. Install the extension
+
+Install it from the
+[Chrome Web Store](https://chromewebstore.google.com/detail/picked-developer-tools/nimmdamgnhlhdpngnalkpmnleebngidh).
+
+## 2. Add the devtools plugin
+
+```typescript
+import { createClient } from '@picked/client'
+import { svelteDevtoolsPlugin } from '@picked/svelte/plugins/devtools'
+
+const picked = createClient({
+  projectId: 'your-project-id',
+  plugins: [svelteDevtoolsPlugin()],
+})
+```
+
+The extension then connects to the SDK.
+
+## 3. Add a tool of your own
+
+A custom tool is a framework-adapted component, and it receives the live Picked client
+exactly as an experience component does.
+
+```typescript
+import { adaptReactComponent } from '@picked/react'
+import { svelteDevtoolsPlugin } from '@picked/svelte/plugins/devtools'
+import MyTool from './MyTool'
+
+const picked = createClient({
+  projectId: 'your-project-id',
+  plugins: [
+    svelteDevtoolsPlugin({
+      customTools: [
+        { id: 'my-tool', label: 'My Tool', component: adaptReactComponent(MyTool) },
+      ],
+    }),
+  ],
+})
+```
+
+Your tools appear under a **Custom Tools** tab. In React use `usePicked()`, and in Svelte
+use `getPicked()`.
+
+## Related
+
+- [Chrome extension](/reference/tools/chrome-extension) — the panel reference.