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

package/dist/docs/how-to/write-a-predicate.md

@@ -0,0 +1,60 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to write a predicate
+
+This guide shows you how to let a condition read data that only your application holds,
+such as a cart total or an account level.
+
+## 1. Define the predicate
+
+Pass a `predicates` object to `createClient()`:
+
+```ts
+import { createClient } from '@picked/client'
+
+const client = createClient({
+  projectId: 'your-project-id',
+  predicates: {
+    'is-example-page': ({ location }) => location?.pathname === '/example',
+    'get-account-tier': async () => {
+      const data = await fetch('/api/get-account-tier').then((r) => r.json())
+      return data.result
+    },
+  },
+})
+```
+
+A predicate returns a boolean, a string, an array of strings, or `undefined`. It can also
+return a promise that resolves to one of those.
+
+## 2. Invoke it from a condition
+
+```ts
+condition: {
+  '==': [
+    { invoke: { var: 'predicates.is-example-page' } },
+    true,
+  ],
+}
+```
+
+:::tip
+A predicate also works inside `validation` logic.
+:::
+
+## Keep it pure and fast
+
+- The same snapshot must always give the same result.
+- Check that a response or a field is there before you read its value. Return `undefined`
+  when the data is not available, and do not throw.
+- The SDK can invoke a predicate many times, so keep the logic small.
+- Do not change the snapshot. It is frozen, and a change to it throws in strict mode.
+
+## Related
+
+- [Predicates](/reference/sdk/predicates) — the state snapshot shape.
+- [About conditions and the logic engine](/explanation/conditions-and-the-logic-engine) —
+  why predicates exist.

package/dist/docs/index.md

@@ -1,88 +1,59 @@
 ---
+type: map
 layout: docs
 ---
 
-# Start here
+# Picked documentation
 
-Picked lets you build personalized UI flows in a visual editor. The SDK then serves
-them to the visitors on your site.
+Picked lets you build personalized UI flows in a visual editor. The SDK then serves them
+to the visitors on your site.
 
-## How it works
+There are two paths to follow. Choose the one that matches your work.
 
-You build experiences in the dashboard with a drag-and-drop flow builder. The SDK
-reads your published experiences and renders them on your site.
+## Work in the dashboard
 
-## Quick start
+Build experiences, write content, and publish.
 
-### 1. Create a project
+Start with [build your first experience](/tutorials/first-experience-in-the-dashboard).
+It takes you from an empty project to a survey on your own site, and it needs no
+development tools.
 
-Sign in to the dashboard and create a project. A project is one site or one
-application.
+One thing must happen first: a developer adds the Picked SDK to your site one time. After
+that, the dashboard is all you need.
 
-See [Projects](/projects) for more detail.
+Then:
 
-### 2. Install the SDK
+- **[Build](/how-to/create-an-experience)** — experiences, flows, conditions, and A/B
+  tests.
+- **[Content](/how-to/define-a-page-layout)** — layouts, sections, pages, and assets.
+- **[Publish](/how-to/publish-a-workspace)** — preview, publish, and roll back.
+- **[Administer and measure](/how-to/invite-and-remove-members)** — members, API keys,
+  analytics, and the tools that connect Picked to Google Tag Manager and to an AI tool.
+- **[Dashboard reference](/reference/dashboard/projects)** — every dashboard screen and
+  every option, plus the [glossary](/reference/glossary).
+- **[How Picked works](/explanation/how-picked-works)** — what happens when you publish.
 
-Add the SDK to your site and start the client. Copy the snippet from your project
-home page.
+## Integrate with code
 
-```typescript
-import { createClient } from '@picked/client'
+Add Picked to a site or an application. Your code then renders the experiences that the
+dashboard describes.
 
-const picked = createClient({
-  projectId: 'your-project-id',
-  plugins: [],
-})
+Start with [add Picked to your application](/tutorials/first-experience). It goes from an
+empty project to a survey that runs in React or in Svelte.
 
-picked.start()
-```
+Read the dashboard documents above also. Everything your code renders is described
+there, so the two paths link to each other rather than repeat.
 
-See [SDK Installation](/sdk) for all setup options.
+Then:
 
-### 3. Register a component
-
-Register your components when you create the client. Each key in the `components`
-object must match a component name that you set in the dashboard.
-
-```typescript
-import { createClient } from '@picked/client'
-
-const picked = createClient({
-  projectId: 'your-project-id',
-  components: {
-    'welcome-survey': YourComponent,
-  },
-})
-
-picked.start()
-```
-
-See [SDK Experiences](/sdk/experiences) for conditions, adapters, and the rules that
-put an experience in a slot.
-
-### 4. Create an experience
-
-In the dashboard, open your project. Click **Experiences**, then **New Experience**.
-Enter a name. Set the component name to match your registered component, for example
-`welcome-survey`.
-
-See [Experiences](/experiences) for the options.
-
-### 5. Build the flow
-
-Open the flow builder. Drag steps, actions, and conditions onto the canvas. Connect
-the nodes to define the path that a visitor takes through the experience.
-
-See [Flow Builder](/flow-builder/overview) for a full guide.
-
-### 6. Save and publish
-
-Click **Save** in the flow builder toolbar. The SDK reads the published experience
-and renders it to each visitor who matches.
-
-## Next steps
-
-- [Flow Builder](/flow-builder/overview) — Build experience flows in a visual editor
-- [Steps](/steps), [Fields](/fields), [Actions](/actions), [Conditions](/conditions)
-  — Set up the parts of an experience
-- [SDK Installation](/sdk) — Full SDK setup and options
+- **[Integrate the SDK](/how-to/install-the-sdk)** — install, register a component, read
+  a feature flag.
+- **[Build a step form](/how-to/render-a-step-form)** — render fields, act on a
+  submission, validate input.
+- **[Server-side rendering](/how-to/server-render-a-page)** — a page that a search engine
+  can read.
+- **[Authenticate](/how-to/authenticate-with-a-password)** — the management API.
+- **[SDK reference](/reference/sdk)**, **[Delivery API](/reference/delivery-api)**,
+  **[PickedQL](/reference/pickedql)**.
+- **[Why it works this way](/explanation/why-server-side-rendering)** — the design
+  behind the SDK.

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

@@ -0,0 +1,53 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../components/Screenshot'
+
+# Actions
+
+An action is a side effect that starts when the flow reaches it. Use an action to
+track an event, to send data to an external service, or to call a webhook.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/actions"
+  alt="The actions list for a workspace on the Picked dashboard"
+/>
+
+## Set up an action
+
+**Name**: The name that the dashboard shows. Your visitors do not see it.
+
+**Key**: The identifier that your application uses for this action. Your visitors do
+not see it.
+
+## Register in your application
+
+Each action key must match a key in the `actions` object that you pass to
+`createClient()`. See
+[How to register an action handler](/how-to/register-an-action-handler) for the code, and
+[SDK actions](/reference/sdk/actions) for what the handler receives and returns.
+
+## Use actions in flows
+
+In the flow builder, drag an action from the library onto the canvas. Connect it to
+the point in the flow where you want it to start.
+
+An action runs when the flow reaches its node. It does not interrupt your visitor. By
+default the flow continues to the next connected node.
+
+An action node can carry a **success** branch and a **failure** branch. Which one the flow
+takes depends on whether your handler throws, and a returned `false` is a success. See
+[How an action decides which way to go](/explanation/how-picked-works#how-an-action-decides-which-way-to-go).
+
+## Reuse actions
+
+An action belongs to the project. Use the same action in more than one experience flow.
+A change to the options of an action applies at every place that uses it.
+
+## Related
+
+- [How to add a step, a field, an action, or a condition](/how-to/add-a-step-field-or-action)
+- [How to register an action handler](/how-to/register-an-action-handler)
+- [SDK actions](/reference/sdk/actions) — what the handler receives and returns.

package/dist/docs/{api-keys.mdx → reference/dashboard/api-keys.mdx}

@@ -1,8 +1,9 @@
 ---
+type: reference
 layout: docs
 ---
 
-import { Screenshot } from '../../components/Screenshot'
+import { Screenshot } from '../../../../components/Screenshot'
 
 # API keys
 
@@ -14,20 +15,10 @@ or for a CI/CD workflow.
   alt="The API keys list for an organization on the Picked dashboard"
 />
 
-## Create an API key
-
-1. Open your organization.
-2. Click **API Keys**.
-3. Click **Create Key**.
-4. Enter a description.
-5. Click **Create**.
-
-Copy the key immediately. The dashboard does not show it again.
-
 ## Use an API key
 
 Put your API key in the `Authorization` header of each request to the
-[Picked API](/api).
+[Picked API](/tutorials/first-api-call).
 
 ```
 Authorization: Bearer your-api-key
@@ -39,7 +30,8 @@ An API key carries scopes, and the scopes limit what the key can reach. Choose t
 scopes that your integration needs when you create the key. A key can do only the
 operations that its scopes permit.
 
-## Revoke a key
+## Related
 
-You can revoke a key at any time from the API keys list. Click the revoke button next
-to the key. A revoked key stops work immediately.
+- [How to create and revoke an API key](/how-to/create-and-revoke-an-api-key)
+- [How to authenticate with an API key](/how-to/authenticate-with-an-api-key) — the API
+  side.

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

@@ -0,0 +1,42 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../components/Screenshot'
+
+# Conditions
+
+A condition evaluates a rule and splits the flow into two paths. One path is for a
+true result, the other for a false result.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/conditions"
+  alt="The conditions list for a workspace on the Picked dashboard"
+/>
+
+## Set up a condition
+
+**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.
+
+## Branches
+
+In the flow builder, a condition node has two output handles. The green handle, for a
+true result, leads to the path for a match. The red handle, for a false result, leads
+to the other path.
+
+You can chain conditions. Connect the output of one condition to the input of another
+to build a decision tree.
+
+## Related
+
+- [How to add a step, a field, an action, or a condition](/how-to/add-a-step-field-or-action)
+
+- [About conditions and the logic engine](/explanation/conditions-and-the-logic-engine) —
+  what a rule can read.
+- [How to write a condition](/how-to/write-a-condition)
+- [Condition builder](/reference/dashboard/flow-builder/condition-builder) — the data
+  sources and the rule structure.

package/dist/docs/reference/dashboard/content/asset-library.mdx

@@ -0,0 +1,63 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../../components/Screenshot'
+
+# Asset Library
+
+The Asset Library holds the files that your content points at. These are images,
+video, documents, and HTML.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/assets"
+  alt="The asset library on the Picked dashboard"
+/>
+
+## Upload and control your assets
+
+The Asset Library is a project-level store. Upload a file, then point at it from any
+Content Entry in the project.
+
+- **Size limit:** 50 MB for each file.
+- **Allowed types:** an image in PNG, JPEG, WebP, AVIF, GIF, or SVG. A video in MP4
+  or WebM. A common document format. HTML, as `text/html`.
+
+Picked rejects a file of another type. It also rejects a file above the size limit.
+
+## HTML assets
+
+Upload a `.html` file and point at it from an **HTML asset** field. Picked then scans
+the file. The scan is advisory: it helps you, and it never stops you. It
+reports findings about speed, about search rank, and about accessibility, so that you
+can improve the file before you publish it:
+
+- **File size:** a warning at 100 KB, and a stronger one at 250 KB.
+- **Inline images:** a note when inline `base64` image data adds about 50 KB or more.
+- **Image dimensions:** an image with no width and no height. Such an image can move
+  the content around it while the page loads.
+- **Lazy load:** an image with no `loading="lazy"` attribute.
+- **Link safety:** an external link with `target="_blank"` and no `rel="noopener"`.
+- **Link search rank:** an external link with no `rel="nofollow"`.
+- **Accessibility:** a pass by `axe-core`. It covers alt text, heading order,
+  contrast, and more.
+
+Every finding is advisory. You can always upload the file as it is.
+
+## How assets are served
+
+Picked serves each asset from a sandboxed storage origin. That origin is separate
+from the trusted origin of your application. HTML therefore comes from its own
+origin, so a document that you upload runs in isolation and cannot reach the page
+that holds it. A script in that document cannot read a session, a token, or the DOM
+around it, because each of those needs same-origin access.
+
+An [Experience Content](/reference/delivery-api/experience-content) response can hold an HTML
+asset. The response then carries the content of that asset, and the SDK renders it
+with no second request to storage.
+
+## Related
+
+- [How to upload and use an asset](/how-to/upload-and-use-an-asset)
+- [Fields](/reference/dashboard/fields) — the field type for an HTML asset.

package/dist/docs/{content → reference/dashboard/content}/content-entries.mdx

@@ -1,8 +1,9 @@
 ---
+type: reference
 layout: docs
 ---
 
-import { Screenshot } from '../../../components/Screenshot'
+import { Screenshot } from '../../../../../components/Screenshot'
 
 # Content Entries
 
@@ -15,11 +16,11 @@ A Content Entry is an instance of a layout filled with real data. A Page renders
 
 ## What a content entry is
 
-A Content Entry is an instance of a layout's schema. The [layout](/content/layouts) defines the fields; the entry holds the actual values. One layout can back many entries, each with its own data.
+A Content Entry is an instance of a layout's schema. The [layout](/reference/dashboard/content/layouts) defines the fields; the entry holds the actual values. One layout can back many entries, each with its own data.
 
 ## How entries bind to pages and steps
 
-A [Page](/content/pages) has a single Step, and that Step links to its entry through the layout content link. A Flow [Step](/steps) backed by a Step Layout binds an entry the same way. When the SDK renders the Page or Step, it resolves the linked entry and hands its data to your component.
+A [Page](/reference/dashboard/content/pages) has a single Step, and that Step links to its entry through the layout content link. A Flow [Step](/reference/dashboard/steps) backed by a Step Layout binds an entry the same way. When the SDK renders the Page or Step, it resolves the linked entry and hands its data to your component.
 
 ## Edit entry data
 
@@ -34,3 +35,10 @@ Invalid data appears as an error on each field. The error carries a path in the
 style, and it points at the exact place in the entry, for example
 `sections[0].data.title`. Fix every error before you publish, because Picked serves
 valid content only.
+
+## Related
+
+- [About the content model](/explanation/the-content-model) — why the schema and the data
+  are separate.
+- [How to fill and publish a page](/how-to/fill-and-publish-a-page)
+- [Page and step layouts](/reference/dashboard/content/layouts)

package/dist/docs/{content → reference/dashboard/content}/layouts.mdx

@@ -1,8 +1,9 @@
 ---
+type: reference
 layout: docs
 ---
 
-import { Screenshot } from '../../../components/Screenshot'
+import { Screenshot } from '../../../../../components/Screenshot'
 
 # Page & Step Layouts
 
@@ -13,13 +14,6 @@ Layouts are reusable JSON schemas. Page Layouts back standalone Pages; Step Layo
   alt="The layouts list in the schema builder on the Picked dashboard"
 />
 
-## What a layout is
-
-A layout is a reusable schema. It defines the fields that a piece of content can
-hold. A layout holds no data itself. A [Content Entry](/content/content-entries)
-creates one copy of a layout and fills it in. The dashboard shows both layout kinds
-under **Models**.
-
 ## A page layout and a step layout
 
 Each layout has a fixed category, and the category decides what the layout gives its
@@ -27,21 +21,8 @@ shape to:
 
 | Layout | It gives its shape to | Who renders it |
 | --- | --- | --- |
-| **Page Layout** | A standalone [Page](/content/pages). | The SDK renders the entry on your server. |
-| **Step Layout** | One [Step](/steps) inside a Flow. | The Step renders the entry in the browser. |
-
-## Create a layout
-
-1. Open your workspace.
-2. Click **Models** in the sidebar.
-3. Click **New Model**.
-4. Choose the category, **Page Layout** or **Step Layout**.
-5. Enter a name and a **Key**. The Key is a unique, stable identifier. Your SDK code
-   and your API calls both use it.
-6. Add your fields. See below.
-7. Save.
-
-The category is fixed at creation and cannot be changed later.
+| **Page Layout** | A standalone [Page](/reference/dashboard/content/pages). | The SDK renders the entry on your server. |
+| **Step Layout** | One [Step](/reference/dashboard/steps) inside a Flow. | The Step renders the entry in the browser. |
 
 ## Field types
 
@@ -59,8 +40,8 @@ A layout is built from fields. Each field has a type that decides its editor and
 | **Color** | A color value. | A theme accent or a swatch. |
 | **JSON** | Any JSON value. | Structured data with no editor of its own. |
 | **Group** | An object of fields inside the layout. | A set of related fields, held together. |
-| **Section** | A [Section](/content/sections) schema inside the layout. | A shared schema fragment that you reuse. |
-| **Asset** | A link to an [Asset Library](/content/asset-library) item. | An image, a video, or a document. |
+| **Section** | A [Section](/reference/dashboard/content/sections) schema inside the layout. | A shared schema fragment that you reuse. |
+| **Asset** | A link to an [Asset Library](/reference/dashboard/content/asset-library) item. | An image, a video, or a document. |
 | **HTML asset** | A link to a `.html` file in your library. | HTML that you wrote before, held inside the content. |
 
 ## Repeatable and grouped fields
@@ -73,14 +54,9 @@ A **Group** field holds a set of fields under one key, and it gives a structured
 object. Make a group repeatable to describe a list of objects, such as a list of
 feature cards.
 
-## Build with sections
-
-A **Section** field holds a reusable [Section](/content/sections) schema inside the
-layout. Define a common structure one time as a Section, such as a hero or a list of
-features. Then point at it from any Page Layout or Step Layout.
-
-## Change a schema
+## Related
 
-A change to the schema of a layout can make a Content Entry invalid. After such
-a change, check each entry that uses the layout again. Fix every field error before
-you publish.
+- [About the content model](/explanation/the-content-model) — why a schema change does not
+  migrate your data.
+- [How to define a page layout](/how-to/define-a-page-layout)
+- [How to reuse a section](/how-to/reuse-a-section)

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/{experiences.mdx → reference/dashboard/experiences.mdx}

@@ -1,8 +1,9 @@
 ---
+type: reference
 layout: docs
 ---
 
-import { Screenshot } from '../../components/Screenshot'
+import { Screenshot } from '../../../../components/Screenshot'
 
 # Experiences
 
@@ -12,7 +13,7 @@ site. Each experience points at a component that you register in your applicatio
 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](/content/pages) for
+for a landing page where the search rank matters. See [Pages](/reference/dashboard/content/pages) for
 that kind.
 
 <Screenshot
@@ -20,19 +21,6 @@ that kind.
   alt="The experiences list for a workspace on the Picked dashboard"
 />
 
-## Create an experience
-
-1. Open your project.
-2. Click **Experiences** in the sidebar.
-3. Click **New Experience**.
-4. Enter a name and a component name. The component name must match a component that
-   you register in your application. See [SDK Experiences](/sdk/experiences) for how
-   to register a component.
-5. Click **Create**.
-
-The flow editor opens with an empty canvas. See
-[Build Flows](/flow-builder/building-flows) to add your first node.
-
 ## Experience settings
 
 Choose no node on the canvas, or click the canvas background, to open the experience
@@ -45,7 +33,7 @@ application.
 
 **Condition**: An optional condition. When you set it, the experience starts only for
 a visitor who matches the condition. See
-[Condition Builder](/flow-builder/condition-builder) for how to write one. Keep it
+[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
@@ -56,3 +44,8 @@ closed until something opens it.
 
 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)