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

package/dist/docs/reference/dashboard/content/pages.mdx

@@ -0,0 +1,35 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../../components/Screenshot'
+
+# Pages
+
+A Page is a standalone, server-rendered experience backed by CMS content, built for SEO-critical landing pages.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/experiences"
+  alt="The experiences list, where Pages and Flows are created on the Picked dashboard"
+/>
+
+## Edit page content
+
+The Page editor has two tabs. The **Properties** tab holds the content of the page.
+The **Settings** tab holds its name, its condition, and its layout. Fill in the
+fields on the **Properties** tab. The inspector on the right edits the field that you
+choose, and the preview panel shows the page while it fills in.
+
+## Change or remove the layout
+
+Use the change-layout control on the **Settings** tab to move the page to another
+Page Layout. When you unlink a layout, Picked separates the Content Entry from the
+page. It deletes no entry, but the page then has no content to render until you
+attach a layout again.
+
+## Related
+
+- [About pages and flows](/explanation/pages-and-flows) — when to choose a Page.
+- [How to fill and publish a page](/how-to/fill-and-publish-a-page)
+- [How to server-render a page](/how-to/server-render-a-page)

package/dist/docs/reference/dashboard/content/sections.mdx

@@ -0,0 +1,28 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../../components/Screenshot'
+
+# Sections
+
+Sections are reusable schema fragments you embed inside layouts, so common structures such as a hero or a feature list are defined once.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/blocks"
+  alt="The sections list in the schema builder on the Picked dashboard"
+/>
+
+## What a section is
+
+A Section is a reusable schema fragment with its own **Key**. A
+[layout](/reference/dashboard/content/layouts) gives its shape to a whole Page or Step. A Section is a
+part that you put into one or more layouts. Define the shape one time, then reuse it
+everywhere.
+
+## Related
+
+- [About the content model](/explanation/the-content-model) — why sections exist.
+- [How to reuse a section](/how-to/reuse-a-section)
+- [Page and step layouts](/reference/dashboard/content/layouts)

package/dist/docs/reference/dashboard/experiences.mdx

@@ -0,0 +1,51 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../components/Screenshot'
+
+# Experiences
+
+An experience is personalized content that Picked serves to the visitors on your
+site. Each experience points at a component that you register in your application.
+
+An experience is either a **Flow** or a **Page**. A **Flow** is an interactive
+experience of more than one step, and the browser renders it. This page covers the
+flow. A **Page** is a standalone experience that the server renders from CMS content,
+for a landing page where the search rank matters. See [Pages](/reference/dashboard/content/pages) for
+that kind.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/experiences"
+  alt="The experiences list for a workspace on the Picked dashboard"
+/>
+
+## Experience settings
+
+Choose no node on the canvas, or click the canvas background, to open the experience
+inspector in the right panel.
+
+**Name**: The name that the dashboard shows. Your visitors do not see it.
+
+**Component Name**: The identifier that points this experience at a component in your
+application.
+
+**Condition**: An optional condition. When you set it, the experience starts only for
+a visitor who matches the condition. See
+[Condition Builder](/reference/dashboard/flow-builder/condition-builder) for how to write one. Keep it
+blank to start the experience for every visitor.
+
+**Initialize Open**: An optional condition that controls whether the experience opens
+by itself when the page loads. When it is blank, the experience loads but stays
+closed until something opens it.
+
+## Experience list
+
+The experiences list shows every experience in the current project. Click an
+experience to open it in the flow builder.
+
+## Related
+
+- [About pages and flows](/explanation/pages-and-flows) — Page or Flow.
+- [How to create an experience](/how-to/create-an-experience)

package/dist/docs/reference/dashboard/features.mdx

@@ -0,0 +1,114 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../components/Screenshot'
+
+# Feature flags
+
+A feature flag lets you run an A/B test and roll a change out in stages. It controls
+which visitors see a change to your site, and you deploy no code.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/features"
+  alt="The feature flags list for a workspace on the Picked dashboard"
+/>
+
+## Keys
+
+Each feature flag has a unique key. Your application uses this key to check whether
+Picked allocates a visitor to the feature flag. You set the key when you create the
+feature flag, and you cannot change it later.
+
+## Set the allocation
+
+Set the allocation from the detail page of the feature flag:
+
+| Control | What it does |
+| --- | --- |
+| **Enabled** | Whether Picked allocates a visitor to the feature flag. A disabled feature flag allocates nobody, and it records nothing. See [Disable a feature flag](#disable-a-feature-flag). |
+| **Weight** | The percentage of visitors that Picked allocates to the feature flag, from 0 to 100. |
+| **Description** | An internal note about what the feature flag tests. |
+
+A feature flag has one weight. For each visitor it gives one of two outcomes:
+allocated, or not allocated. A weight of 30 allocates 30% of your visitors. The other
+70% stay unallocated. A weight of 0 allocates nobody. A weight of 100 allocates
+everybody.
+
+## How Picked allocates a visitor
+
+The allocation is deterministic. It derives from the visitor ID, the ID of the feature
+flag, and the weight. Each feature flag gets its own value, so tests that run at the
+same time are independent. See
+[About feature flag allocation](/explanation/feature-flag-allocation).
+
+## Disable a feature flag
+
+A disabled feature flag allocates nobody, and it records nothing. The difference
+from a weight of 0 matters for your reports. The visitor is **not in the test at
+all**, and the visitor is not in the control group.
+
+The SDK does not evaluate a disabled feature flag. It stores no decision in the
+browser of the visitor, and it reports no decision to your analytics. Such a feature
+flag is absent from the feature list on every analytics event.
+
+An experience whose condition points at a disabled feature flag behaves as though
+the visitor is not in the test. The condition reads as not allocated, and Picked
+records no assignment.
+
+This state is temporary, and it discards no decision that Picked made already. A
+visitor who was allocated before keeps that decision in the browser. When you enable the
+feature flag again, Picked continues from that decision, and the visitor stays in the
+group they were already in.
+
+:::note
+Expect a step change in your reports when you disable a feature flag: fewer feature
+flags for each visitor, and fewer decision events. That is the feature flag that drops
+out, and you lose no data.
+:::
+
+A disabled feature flag stays visible in the developer tools, and a
+[URL override](/reference/sdk/features#overrides-in-the-url) still turns one on for QA.
+
+## Feature flag versions
+
+Each feature flag has a version number, and it starts at 1. The SDK caches an
+allocation decision in the browser of the visitor under a key, and the version is part
+of that key. The version does nothing else, and it is not an input to the allocation
+value. When you increment the version, the SDK discards those cached decisions. It
+then evaluates every visitor again on the next page load.
+
+### What happens when you increment the version
+
+- **The SDK invalidates the cached decisions.** The cache key holds the version, so the
+  old entry no longer matches and the feature flag counts as undecided.
+- **Picked evaluates each visitor against the current weight.** The allocation is
+  deterministic and the version is not one of its inputs, so the same visitor against
+  an unchanged weight gives the same result.
+- **You cannot reverse this.** There is no way to decrement a version.
+
+:::note
+The new version does not move your visitors between groups. It clears the cached
+decisions and runs the allocation again. With an unchanged weight, everybody lands
+where they were before. Change the weight to move your visitors.
+:::
+
+### When to increment
+
+Increment the version after you change the weight. Do this when you want Picked to
+evaluate an allocated visitor again against the new weight, and not to use the cached
+decision.
+
+### When not to increment
+
+To apply a weight change only to a visitor that Picked does not allocate yet, change
+the weight and leave the version as it is. An allocated visitor keeps the current
+allocation.
+
+## Related
+
+- [About feature flag allocation](/explanation/feature-flag-allocation)
+- [How to run an A/B test](/how-to/run-an-ab-test)
+- [How to read a feature flag](/how-to/read-a-feature-flag)
+- [How to add a step, a field, an action, or a condition](/how-to/add-a-step-field-or-action)

package/dist/docs/reference/dashboard/fields.mdx

@@ -0,0 +1,100 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../components/Screenshot'
+
+# Fields
+
+A field is a data input that a visitor sees inside a step. A field collects
+information such as a name, an email address, a preference, or a choice.
+
+This page covers the experience field, which collects visitor input. An experience
+field is not the same as a content field. A content field is part of the schema of a
+CMS layout. See [Page and Step Layouts](/reference/dashboard/content/layouts) for those.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/fields"
+  alt="The fields list for a workspace on the Picked dashboard"
+/>
+
+## Field types
+
+A field has one of many types. These are the common ones:
+
+`TEXT`: A string input. Use it for a name, an email address, or free text.
+
+`NUMBER`: A numeric input. Use it for a quantity, a rating, or an age.
+
+`BOOLEAN`: A true or false toggle. Use it for a checkbox or for consent.
+
+`OBJECT`: A structured data input. Use it for data that holds other data.
+
+## Options
+
+**Name**: The name that the dashboard shows. Your visitors do not see it.
+
+**Key**: The identifier for your application. You set it once and you cannot change
+it. Your visitors do not see it.
+
+**Label**: The label that a visitor sees next to the field.
+
+**Placeholder**: The hint text that the input shows while it is empty.
+
+**Description**: A longer description of what the field is for. The dashboard shows
+it. Your visitors do not see it.
+
+**Help Text**: Text below the field that helps your visitors.
+
+**Default Value**: The value that the field holds when it loads.
+
+## Validation
+
+**Required**: When this is on, a visitor must fill in the field before the flow can
+continue.
+
+**Validation rules**: Conditions for a constraint such as a smallest value, a largest
+value, or a pattern. See [Condition Builder](/reference/dashboard/flow-builder/condition-builder) for how
+to build a validation rule.
+
+## More than one value
+
+Turn on **Multiple** to let a visitor send more than one value for the field. This is
+useful for an input that takes several choices, or for a field of tags.
+
+## Choices
+
+For a field with a fixed set of choices, such as a dropdown or a set of radio
+buttons, add options. Each option has a value, and the response carries that value.
+
+Each option can also carry a condition. When you set one, the option appears only to
+a visitor who matches the condition. See
+[Condition Builder](/reference/dashboard/flow-builder/condition-builder) for more detail.
+
+## Privacy
+
+Two policies control where the value of a field can go. They are independent, and a
+sensitive field usually needs both.
+
+| Policy | What it does |
+| --- | --- |
+| **Do Not Track** | Picked keeps the value out of your analytics events. The events carry the field ID only. |
+| **Do Not Store** | The SDK reads the value but does not put it in browser storage. |
+
+Neither policy stops the flow from the use of the value inside the page. A field with both
+policies set still holds its value there. The flow validates the step with it, and it
+evaluates the conditions after the step with it. The policies control what leaves the
+page.
+
+Set both for a password, a tax number, or a payment detail. A field that only takes a
+branch in a flow needs neither.
+
+## Related
+
+- [How to add a step, a field, an action, or a condition](/how-to/add-a-step-field-or-action)
+
+- [How to validate a field](/how-to/validate-a-field)
+- [How to write a condition](/how-to/write-a-condition) — for a validation rule or an
+  option condition.
+- [SDK fields](/reference/sdk/fields) — the `policies` object.

package/dist/docs/reference/dashboard/flow-builder/canvas.mdx

@@ -0,0 +1,58 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../../components/Screenshot'
+
+# Flow builder
+
+The flow builder is a visual editor for an experience flow. You drag a block onto a
+canvas, connect the blocks with arrows, and set the options of each node in an
+inspector panel.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/experiences/{experienceId}"
+  alt="The flow builder with the library, canvas, and inspector panels"
+/>
+
+## Layout
+
+The flow builder has three panels, from left to right.
+
+**Library**, on the left: it lists every step, action, condition, and field in
+your project. Drag an item from here onto the canvas.
+
+**Canvas**, in the middle: the area where you build your flow. A node stands for a
+block. An arrow stands for a connection between two blocks.
+
+**Inspector**, on the right: it shows the options of the node that you choose. When
+you choose no node, it shows the settings of the experience.
+
+## Panel controls
+
+Drag a divider between two panels to change their size. Press `Cmd/Ctrl+\` to turn
+both side panels on and off. Press `Cmd/Ctrl+Shift+\` to turn the inspector on and
+off.
+
+## Move around the canvas
+
+**Zoom**: scroll to make the view larger or smaller.
+
+**Pan**: choose the hand tool with `H`, then drag. You can also hold `Space` and
+drag. A drag with the middle mouse button also pans.
+
+**Choose tool**: press `V` to go back to the default tool.
+Click to choose a node. Drag on empty space to choose every node inside a rectangle.
+
+## Auto-layout
+
+Click the auto-layout button in the toolbar. The flow builder then arranges every
+node into a clean hierarchy. This is useful after you add many nodes, and when the
+canvas becomes messy.
+
+## Related
+
+- [How to build a flow](/how-to/build-a-flow) — add, connect, and branch.
+- [Keyboard shortcuts](/reference/dashboard/flow-builder/keyboard-shortcuts)
+- [Nodes](/reference/dashboard/flow-builder/nodes)

package/dist/docs/reference/dashboard/flow-builder/condition-builder.md

@@ -0,0 +1,57 @@
+---
+type: reference
+layout: docs
+---
+
+# Condition builder
+
+The condition builder is a visual rule editor, and the dashboard uses it in several
+places. With it you define a rule and you write no code.
+
+## Where it appears
+
+The dashboard uses the condition builder here:
+
+- **Condition nodes** — they set which branch the flow takes in the
+  [flow builder](/reference/dashboard/flow-builder/canvas).
+- **Experience conditions** — they control when an experience starts for a visitor.
+- **Initialize open conditions** — they control when an experience opens by itself as
+  the page loads.
+- **Field option conditions** — they show or hide one option, and the state of the
+  visitor decides which.
+
+## Rule structure
+
+The builder holds your rules in groups. Each group uses **AND** or **OR**. With
+**AND**, every rule must match. With **OR**, one rule must match.
+
+A single rule has three parts:
+
+1. **Field** — the data source to evaluate.
+2. **Operator** — how to compare. Examples are equals, not equals, greater than, and
+   contains.
+3. **Value** — the value to compare against.
+
+You can put a group inside another group to build a larger rule. An example is an AND
+group that holds two OR groups.
+
+## Data sources
+
+A rule can point at these data sources:
+
+**Responses** — the values that your visitors send through the form fields of the
+current experience. Each field that you create in your project appears here under its
+name.
+
+**Actions** — the actions that ran during the flow.
+
+**Feature flags** — the state of each feature flag in your project. Use it to take a
+branch on whether Picked allocates a visitor to a flag.
+
+**Location** — the parts of the current page URL of the visitor. These are the
+pathname, the search parameters, the hostname, and the hash.
+
+## Related
+
+- [How to write a condition](/how-to/write-a-condition) — a worked example.
+- [About conditions and the logic engine](/explanation/conditions-and-the-logic-engine)

package/dist/docs/reference/dashboard/flow-builder/keyboard-shortcuts.md

@@ -0,0 +1,72 @@
+---
+type: reference
+layout: docs
+---
+
+# Keyboard shortcuts
+
+These shortcuts work when the canvas of the flow builder holds the keyboard input.
+
+## Canvas tools
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| `V` | `V` | The choose tool |
+| `H` | `H` | The hand tool, which pans the view |
+| `Space`, held | `Space`, held | The hand tool, while you hold the key |
+
+## Layout
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| `Shift+L` | `Shift+L` | Auto-layout |
+
+## Choice
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| `Cmd+A` | `Ctrl+A` | Choose every node |
+| `Escape` | `Escape` | Choose no node |
+
+## Edits
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| `Cmd+D` | `Ctrl+D` | Make a copy of each chosen node |
+| `Delete` or `Backspace` | `Delete` or `Backspace` | Delete each chosen node |
+| `Cmd+Z` | `Ctrl+Z` | Undo |
+| `Cmd+Shift+Z` | `Ctrl+Shift+Z` | Redo |
+
+## Movement
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| Arrow keys | Arrow keys | Move each chosen node a small distance |
+| `Shift` and an arrow key | `Shift` and an arrow key | Move each chosen node further |
+
+## Zoom
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| Scroll | Scroll | Zoom in or out |
+| Pinch | Pinch | Zoom in or out, on a trackpad |
+| `Cmd+=` | `Ctrl+=` | Zoom in |
+| `Cmd+-` | `Ctrl+-` | Zoom out |
+| `Shift+1` | `Shift+1` | Fit the flow to the view |
+| `Shift+0` | `Shift+0` | Zoom to 100% |
+
+## Panels
+
+| Shortcut (Mac) | Shortcut (PC) | Action |
+| --- | --- | --- |
+| `Cmd+\` | `Ctrl+\` | Turn both side panels on or off |
+| `?` | `?` | Turn this shortcut list on or off |
+
+---
+
+[Overview](/reference/dashboard/flow-builder/canvas) · [Nodes](/reference/dashboard/flow-builder/nodes) · [Build Flows](/how-to/build-a-flow) · **Keyboard Shortcuts** · [Condition Builder](/reference/dashboard/flow-builder/condition-builder)
+
+## Related
+
+- [How to build a flow](/how-to/build-a-flow)
+- [Canvas](/reference/dashboard/flow-builder/canvas) — the panels and the view controls.

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

@@ -0,0 +1,63 @@
+---
+type: reference
+layout: docs
+---
+
+# Nodes
+
+A node is one part of a flow. Each node stands for a block in your experience. There
+are four node types.
+
+## Origin
+
+Every flow starts with an origin node. It is a gray circle on the left side of the
+canvas, and it has one output handle on its right side.
+
+You cannot move the origin, delete it, or make a copy of it. It is always there.
+
+## Step
+
+A step node stands for a screen that a visitor sees. It appears as a blue rectangle
+on the canvas.
+
+A step holds fields. Drag a field from the library onto a step node to assign
+it. The subtitle of the node gives the number of assigned fields.
+
+Each step has a `layoutName`. It tells the SDK which visual layout to use for this
+step. Set the layout name in the inspector.
+
+## Action
+
+An action node stands for a side effect. A side effect happens where the visitor
+cannot see it. The node appears as a green rectangle.
+
+An action runs when the flow reaches it. Use an action to record an event, to send
+data, or to start an integration.
+
+## Condition
+
+A condition node stands for a point where the flow splits. It appears as an amber
+rectangle.
+
+A condition node has two output handles, and not one. The green handle at the top
+right connects to the path for a true result. The red handle at the bottom right
+connects to the path for a false result.
+
+Define the rule in the inspector, with the visual condition builder. See
+[Conditions](/reference/dashboard/conditions) for more detail.
+
+## Handles
+
+A handle is a connection point on a node. An input handle is on the left. An output
+handle is on the right. Drag from an output handle to an input handle to connect two
+nodes.
+
+---
+
+[Overview](/reference/dashboard/flow-builder/canvas) · **Nodes** · [Build Flows](/how-to/build-a-flow) · [Keyboard Shortcuts](/reference/dashboard/flow-builder/keyboard-shortcuts) · [Condition Builder](/reference/dashboard/flow-builder/condition-builder)
+
+## Related
+
+- [How to build a flow](/how-to/build-a-flow)
+- [Canvas](/reference/dashboard/flow-builder/canvas)
+- [About how Picked works](/explanation/how-picked-works) — why a flow is a graph.

package/dist/docs/reference/dashboard/projects.mdx

@@ -0,0 +1,44 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../components/Screenshot'
+
+# Projects
+
+A project is one site or one application that you want to measure with Picked. Each
+project has its own experiences, content, and options.
+
+<Screenshot
+  route="/{orgSlug}"
+  alt="The organization home page on the Picked dashboard, with the projects in an organization"
+/>
+
+## Workspaces
+
+Each project holds one or more [Workspaces](/reference/dashboard/workspaces). In a workspace you set the
+options for an experience and you see a preview of it before you make it live.
+
+## Project home
+
+When you open a project, you land on the project home page. It shows your SDK
+snippet and a list of the setup tasks that are still open.
+
+Copy the snippet and add it to your site. The snippet connects your site to the
+project and lets Picked serve experiences to it. See
+[SDK Installation](/reference/sdk) for the setup detail.
+
+## Project navigation
+
+The sidebar shows the sections of your project: **Feature flags**, **Fields**, **Flows**,
+**Pages**, and **Workspace settings**. **Flows** holds **Step Layouts**, and **Pages**
+holds **Page Layouts** and **Sections**.
+
+A step, an action, and a condition have no sidebar entry. You reach all three from the
+library in the flow builder, because each one belongs to a flow.
+
+## Related
+
+- [How to create a project](/how-to/create-a-project)
+- [How to install the SDK](/how-to/install-the-sdk)

package/dist/docs/reference/dashboard/reports.mdx

@@ -0,0 +1,43 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../components/Screenshot'
+
+# Reports
+
+A report is an embedded Metabase dashboard or question, attached to a Picked project. Use
+a report to see how your visitors move through your experiences and your feature flags.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/reports"
+  alt="The reports list for a project on the Picked dashboard"
+/>
+
+## Report options
+
+| Option | Description |
+| --- | --- |
+| **Report name** | The name that the reports list shows. |
+| **Description** | An optional note about what the report shows. |
+| **Metabase report type** | `Dashboard` or `Question`. |
+| **Metabase report ID** | The numeric ID from the Metabase URL. |
+| **Display order** | Optional. It controls the position of the report in the list. |
+
+The create form has a link that opens the report, so you can check that the ID is
+correct before you save.
+
+## Permissions
+
+A member needs permission in the organization to create, edit, or delete a report. The
+dashboard hides those actions from a member without it.
+
+## Delete a report
+
+Open the report settings page and click **Delete report**. You cannot reverse a delete.
+
+## Related
+
+- [Analytics queries](/how-to/analytics) — query the same data with SQL.
+- [About PickedQL](/explanation/how-pickedql-works) — what the query layer expands.