picked 0.0.101-next.2 → 0.0.101

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

@@ -0,0 +1,39 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to reuse a step, a field, or an action
+
+This guide shows you how to use one step, field, action, or condition in more than one
+flow. All four belong to the project, and not to the experience that you made them in.
+
+## Steps
+
+1. Open the flow builder for the second experience.
+2. Find the step, the action, or the condition in the library on the left.
+3. Drag it onto the canvas, or onto a step node for a field.
+
+The same one now appears in both flows.
+
+:::warning
+A change to the options applies at every place that uses it. Check the other flows before
+you change a shared step, field, action, or condition.
+:::
+
+## API and MCP
+
+You can also do this task with the [Management API](/reference/management-api/schema), the [MCP server](/reference/tools/mcp), or code that you send to [`picked_run`](/reference/tools/mcp-run).
+
+| Task | GraphQL | MCP tool | Run |
+| --- | --- | --- | --- |
+| Find the step, the action, or the condition | [`steps`](/reference/management-api/schema/step#steps), [`actions`](/reference/management-api/schema/action#actions), [`conditions`](/reference/management-api/schema/condition#conditions) | [`list_steps`](/reference/tools/mcp#list_steps), [`list_actions`](/reference/tools/mcp#list_actions), [`list_conditions`](/reference/tools/mcp#list_conditions) | `tools.list_steps({ workspace_id })`, `tools.list_actions({ workspace_id })`, `tools.list_conditions({ workspace_id })` |
+| Add it to the flow of a second experience | [`experienceFlowUpdate`](/reference/management-api/schema/experience#experienceflowupdate) | [`update_experience_flow`](/reference/tools/mcp#update_experience_flow) | `tools.update_experience_flow({ experience_id, workspace_id, create_steps, create_nodes })` |
+| Assign a field to a step | [`stepUpdate`](/reference/management-api/schema/step#stepupdate), [`experienceFlowUpdate`](/reference/management-api/schema/experience#experienceflowupdate) | [`update_experience_flow`](/reference/tools/mcp#update_experience_flow) | `tools.update_experience_flow({ experience_id, workspace_id, update_steps })` |
+| Find the steps that use a field | [`field`](/reference/management-api/schema/field#field) | [`get_field`](/reference/tools/mcp#get_field) | `tools.get_field({ field_id })` |
+
+## Related
+
+- [Steps](/reference/dashboard/steps) — the step options.
+- [Fields](/reference/dashboard/fields) — the field options.
+- [Actions](/reference/dashboard/actions) — the action options.

package/docs/how-to/roll-back-a-published-version.md

@@ -0,0 +1,39 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to roll back a published version
+
+This guide shows you how to make an earlier published version live again. Your current
+draft does not change.
+
+## Steps
+
+1. Open **Publish history** from the project sidebar.
+2. Find the version that you want to restore.
+3. Click **Restore**.
+4. Read the diff preview. It compares the current live version against the one that you
+   chose.
+5. Click **Restore this version** to confirm.
+
+The restored version is live immediately.
+
+## API and MCP
+
+You can also do this task with the [Management API](/reference/management-api/schema), the [MCP server](/reference/tools/mcp), or code that you send to [`picked_run`](/reference/tools/mcp-run).
+
+| Task | GraphQL | MCP tool | Run |
+| --- | --- | --- | --- |
+| Find the version | [`project`](/reference/management-api/schema/project#project) | [`list_workspace_versions`](/reference/tools/mcp#list_workspace_versions) | `tools.list_workspace_versions({ project_id })` |
+| Read the diff | [`workspaceDiff`](/reference/management-api/schema/workspace-version#workspacediff) | [`compare_workspace_versions`](/reference/tools/mcp#compare_workspace_versions) | `tools.compare_workspace_versions({ base_version_id, compare_version_id })` |
+| Restore the version | [`workspaceVersionPublish`](/reference/management-api/schema/workspace#workspaceversionpublish) | [`guide_workspace_version_publish`](/reference/tools/mcp#guide_workspace_version_publish) | `tools.guide_workspace_version_publish({ workspace_version_id })` |
+
+The MCP server does not restore a version. `guide_workspace_version_publish` gives the
+link to the **Publish history** page in the dashboard.
+
+## Related
+
+- [About workspaces and versions](/explanation/workspaces-and-versions) — why a roll-back
+  changes no data.
+- [Publish history](/reference/dashboard/workspace-versioning) — the version list.

package/docs/how-to/run-an-ab-test.md

@@ -0,0 +1,59 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to run an A/B test
+
+This guide shows you how to split your traffic with a feature flag and read the result in
+your application.
+
+Read [About feature flag allocation](/explanation/feature-flag-allocation) first. The
+point at which you read the feature flag decides when a visitor enters the test.
+
+## 1. Create the feature flag
+
+1. Open your project.
+2. Click **Feature flags** in the sidebar.
+3. Click **New feature flag**.
+4. Enter a name.
+5. Click **Create feature flag**.
+
+You cannot change the key after you create the feature flag.
+
+## 2. Set the allocation
+
+Open the detail page of the feature flag and set these controls:
+
+1. Turn **Enabled** on. A feature flag that is off allocates nobody.
+2. Set **Weight** to the percentage of visitors that you want in the test.
+3. Enter a **Description** that says what the feature flag tests.
+
+## 3. Read the feature flag in your application
+
+See [How to read a feature flag](/how-to/read-a-feature-flag). Read it at the point where
+the decision matters, and not at startup.
+
+## 4. Change the weight later
+
+1. Change **Weight** on the detail page.
+2. Increment the version.
+
+The new weight then applies to a visitor with a cached decision. Leave the version as it
+is to apply the new weight only to a visitor who is not allocated yet.
+
+## API and MCP
+
+You can also do this task with the [Management API](/reference/management-api/schema), the [MCP server](/reference/tools/mcp), or code that you send to [`picked_run`](/reference/tools/mcp-run).
+
+| Task | GraphQL | MCP tool | Run |
+| --- | --- | --- | --- |
+| Create the feature flag | [`featureCreate`](/reference/management-api/schema/feature#featurecreate) | [`create_feature`](/reference/tools/mcp#create_feature) | `tools.create_feature({ workspace_id, name, variants })` |
+| Set the allocation | [`featureUpdate`](/reference/management-api/schema/feature#featureupdate) | [`update_feature`](/reference/tools/mcp#update_feature) | `tools.update_feature({ feature_id, workspace_id, weight })` |
+| Change the weight and increment the version | [`featureUpdate`](/reference/management-api/schema/feature#featureupdate) | [`update_feature`](/reference/tools/mcp#update_feature) | `tools.update_feature({ feature_id, workspace_id, weight, increment_version: true })` |
+
+## Related
+
+- [About feature flag allocation](/explanation/feature-flag-allocation) — why two feature
+  flags at the same weight give four groups, not two.
+- [Feature flags](/reference/dashboard/features) — the controls.

package/docs/how-to/run-code-on-a-form-submission.md

@@ -0,0 +1,125 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to run code on a form submission
+
+This guide shows you how to act on a step submission. Pass your callbacks to `useStep()`
+in React, or to `getStep()` in Svelte.
+
+## What the SDK does on submit
+
+1. It collects the field values from the HTML form.
+2. It runs each `onBeforeSubmit` callback, one after another.
+3. It checks each required field and each validation rule.
+4. It commits the responses to the experience state.
+5. It fires `form_submit_success` or `form_submit_error` on the event bus.
+6. It runs your `onSuccess` or `onError` callback.
+7. It moves to the next step.
+
+## Change the data before it is stored
+
+:::code-group
+
+```tsx [React]
+const { form } = useStep({
+  onBeforeSubmit: async (data) => ({
+    ...data,
+    'email-address': String(data['email-address']).toLowerCase(),
+  }),
+})
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  const { form } = getStep({
+    onBeforeSubmit: async (data) => ({
+      ...data,
+      'email-address': String(data['email-address']).toLowerCase(),
+    }),
+  })
+</script>
+```
+
+:::
+
+:::warning
+An `onBeforeSubmit` callback that throws aborts the submit before the SDK commits
+anything, and the step does not advance. Use it for a transform and for a check. Put a
+side effect, such as an analytics call, in `onSuccess`.
+:::
+
+## Act on the outcome
+
+:::code-group
+
+```tsx [React]
+const { form } = useStep({
+  onSuccess: ({ data }) => analytics.track('lead_captured', data),
+  onError: (errors) => console.error('Validation errors:', errors),
+})
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  const { form } = getStep({
+    onSuccess: ({ data }) => analytics.track('lead_captured', data),
+    onError: (errors) => console.error('Validation errors:', errors),
+  })
+</script>
+```
+
+:::
+
+A callback belongs to the component that passes it, and the SDK releases it when that
+component unmounts. An `onSuccess` callback that throws cannot stop the flow. The SDK
+reports the failure as `form_submit_callback_error`.
+
+## Choose the next step yourself
+
+Call `stopNavigation()` inside `onSuccess`, then move where you want:
+
+:::code-group
+
+```tsx [React]
+const experience = useExperience()
+
+const { form } = useStep({
+  onSuccess: ({ data, stopNavigation }) => {
+    stopNavigation()
+    if (data['plan-type'] === 'enterprise') {
+      experience.goToStepById('enterprise-contact')
+    } else {
+      experience.goToNextStep()
+    }
+  },
+})
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  const experience = getExperience()
+
+  const { form } = getStep({
+    onSuccess: ({ data, stopNavigation }) => {
+      stopNavigation()
+      if (data['plan-type'] === 'enterprise') {
+        experience.goToStepById('enterprise-contact')
+      } else {
+        experience.goToNextStep()
+      }
+    },
+  })
+</script>
+```
+
+:::
+
+`goToStepById()` takes a step `id`. `goToStepByKey()` takes the key of the step. When no
+step matches, the call does nothing.
+
+## Related
+
+- [How to render a step form](/how-to/render-a-step-form).
+- [SDK steps](/reference/sdk/steps) — the `form` object.

package/docs/how-to/server-render-a-page.md

@@ -0,0 +1,81 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to server-render a page
+
+This guide shows you how to render a Picked Page on your server and hydrate it in the
+browser. You need a published Page and a server that renders React or Svelte.
+
+## 1. Make the snapshot
+
+Create one client for each request, then call `serialize()`:
+
+```ts
+import { createClient } from 'picked'
+import { serialize } from '@picked/client/server'
+
+const client = createClient(options)
+
+const snapshot = await serialize(client, {
+  projectConfig,
+  attributes: { location: { pathname: url.pathname } },
+})
+```
+
+:::warning
+Give `serialize()` one client for each request. It does not support two calls at the same
+time on one client.
+:::
+
+## 2. Embed the snapshot
+
+```ts
+const html = `
+  <div id="root">${appHtml}</div>
+  <script>window.__PICKED__ = ${JSON.stringify(snapshot)}</script>
+`
+```
+
+## 3. Seed the client and render the slot
+
+:::code-group
+
+```tsx [React]
+import { PickedProvider, ExperienceSlot } from '@picked/react'
+
+export function Page({ snapshot }) {
+  return (
+    <PickedProvider options={options} snapshot={snapshot}>
+      <ExperienceSlot name="page" />
+    </PickedProvider>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { ExperienceSlot, setPickedContext } from '@picked/svelte'
+
+  const { snapshot } = $props()
+  setPickedContext({ options, snapshot })
+</script>
+
+<ExperienceSlot name="page" />
+```
+
+:::
+
+The provider seeds the client at once, so the server HTML and the first paint match.
+
+## 4. Point the experience at the slot
+
+Set the target selector of your Page experience to `.picked-slot-page`, then publish.
+
+## Related
+
+- [About server-side rendering](/explanation/why-server-side-rendering) — why the
+  snapshot carries condition results.
+- [Server snapshot](/reference/sdk/ssr/serialize) — every parameter.
+- [Your first server-rendered page](/tutorials/first-server-rendered-page).

package/docs/how-to/set-a-content-security-policy.md

@@ -0,0 +1,32 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to set a Content Security Policy
+
+This guide shows you how to let the Picked SDK load its resources under a CSP.
+
+## Steps
+
+Add the Picked domains to your policy.
+
+As an HTTP header:
+
+```
+Content-Security-Policy: connect-src 'self' https://api.picked.app https://evnts.pckd.dev; img-src 'self' https://img.picked-content.com;
+```
+
+Or as a `<meta>` tag:
+
+```html
+<meta
+  http-equiv="Content-Security-Policy"
+  content="connect-src 'self' https://api.picked.app https://evnts.pckd.dev; img-src 'self' https://img.picked-content.com;"
+/>
+```
+
+## Related
+
+- [Content Security Policy](/reference/sdk/content-security-policy) — what each domain is
+  for.

package/docs/how-to/set-up-mfa.md

@@ -0,0 +1,126 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to set up MFA
+
+This guide shows you how to add an authenticator app to an account, and how to sign in
+with it. Picked supports TOTP authenticator apps only, such as Google Authenticator.
+Every MFA mutation needs authentication.
+
+## Who must use MFA
+
+Picked staff, and every member of an organization that requires MFA, must sign in with an
+authenticator app. For these users, most operations return the error code `MFA_REQUIRED`
+until the session reaches `AAL2`. The operations that a session at `AAL1` can use are in
+[Authenticator assurance levels](/reference/management-api/authentication#authenticator-assurance-levels).
+The `user.mfa` field tells you where a user stands:
+
+```graphql
+query {
+  user {
+    mfa { required reason enrolled satisfied }
+  }
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `required` | The user must hold an `AAL2` session to use the fields that need it. |
+| `reason` | `STAFF` or `ORGANIZATION`. Empty when `required` is false. |
+| `enrolled` | The user holds a verified authenticator. |
+| `satisfied` | The session that made the request meets the requirement. |
+
+## 1. Add an authenticator
+
+```graphql
+mutation {
+  mfaFactorEnroll(input: { friendlyName: "Work phone" }) {
+    factor { id factorType status }
+    totp { qrCode secret uri }
+  }
+}
+```
+
+A new factor has the status `UNVERIFIED`. Show `qrCode` (SVG markup) for the user to scan,
+or `secret` for the user to enter into the app. The API returns it one time only.
+
+Before it adds the factor, the mutation deletes the caller's factors that are not verified.
+But it keeps the two newest of these factors if they are less than 60 seconds old. A
+different setup can still use them, for example in a different browser tab. The mutation
+also deletes a factor that is not verified and has the `friendlyName` that you give.
+Therefore, a setup that did not finish does not stop a new setup.
+
+## 2. Open a challenge
+
+```graphql
+mutation {
+  mfaChallengeCreate(input: { factorId: "factor-id" }) {
+    challengeId
+    expiresAt
+  }
+}
+```
+
+## 3. Verify the code
+
+```graphql
+mutation {
+  mfaChallengeVerify(input: {
+    factorId: "factor-id"
+    challengeId: "challenge-id"
+    code: "123456"
+  }) {
+    session { accessToken refreshToken aal }
+  }
+}
+```
+
+The session moves to `AAL2`, and the factor status changes to `VERIFIED`. Use the returned
+tokens from this point. A wrong code returns `MFA_CHALLENGE_FAILED`.
+
+## Sign in with an authenticator
+
+After `sessionCreate`, the session is at `AAL1`. When `session.user.mfa.enrolled` is
+`true`, do steps 2 and 3 against one of the user's verified factors. The query
+`user { mfaFactors { id status } }` lists them. When `required` is `true` and `enrolled`
+is `false`, do steps 1 to 3.
+
+## Remove an authenticator
+
+```graphql
+mutation {
+  mfaFactorUnenroll(input: { factorId: "factor-id" }) {
+    success
+  }
+}
+```
+
+To remove a verified factor, the session must be at `AAL2`. An `AAL1` session receives
+`MFA_REQUIRED`.
+
+A user who must use MFA always keeps at least one authenticator. A request to remove
+their last one fails with `VALIDATION_ERROR`. To replace an authenticator, add the new
+one first, then remove the old one. A user with the `users/reset_mfa` scope clears the
+last one with `userMfaReset`.
+
+## API and MCP
+
+You can also do this task with the [Management API](/reference/management-api/schema), the [MCP server](/reference/tools/mcp), or code that you send to [`picked_run`](/reference/tools/mcp-run).
+
+| Task | GraphQL | MCP tool | Run |
+| --- | --- | --- | --- |
+| Read the MFA status of the user | [`user`](/reference/management-api/schema/auth#user) | None | None |
+| Add an authenticator | [`mfaFactorEnroll`](/reference/management-api/schema/auth#mfafactorenroll) | None | None |
+| Open a challenge | [`mfaChallengeCreate`](/reference/management-api/schema/auth#mfachallengecreate) | None | None |
+| Verify the code | [`mfaChallengeVerify`](/reference/management-api/schema/auth#mfachallengeverify) | None | None |
+| Sign in with an authenticator | [`sessionCreate`](/reference/management-api/schema/auth#sessioncreate), [`mfaChallengeCreate`](/reference/management-api/schema/auth#mfachallengecreate), [`mfaChallengeVerify`](/reference/management-api/schema/auth#mfachallengeverify) | None | None |
+| Remove an authenticator | [`mfaFactorUnenroll`](/reference/management-api/schema/auth#mfafactorunenroll) | None | None |
+
+## Related
+
+- [Authentication](/reference/management-api/authentication) — every mutation and the
+  assurance levels.
+- [Authorization and scopes](/reference/management-api/authorization-and-scopes) — who
+  can reset the MFA of another user.

package/docs/how-to/switch-workspaces.md

@@ -0,0 +1,122 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to switch workspaces
+
+This guide shows you how to point your local tooling at a different project or workspace.
+Your application then renders that workspace's content and types on your machine. It expects
+a `picked.config.ts` and the [CLI](/reference/tools/cli).
+
+Your tooling reads the project and surface named in the committed `picked.config.ts`. The
+CLI writes your choice to `.picked/settings.json` instead. That file is per-developer and
+Git ignores it, so the committed default stays as it is and one command puts it back.
+
+See [Workspaces](/reference/dashboard/workspaces) for what Live, Draft, and Archived mean.
+
+## 1. Sign in
+
+```bash
+picked login
+```
+
+This opens your browser for a one-time OAuth sign-in and stores a session under
+`~/.picked/`. Confirm it with `picked whoami`. See
+[CLI authentication](/how-to/authenticate-the-cli).
+
+## 2. Find a workspace
+
+```bash
+picked workspace list
+```
+
+```
+Acme Corp. (acme-corporation)
+  Storefront [proj_a1b2]
+    Default Storefront [LIVE] (live)
+    Checkout rework [DRAFT]
+```
+
+Note the **project id** (`proj_a1b2`) and the name or the id of the workspace you want.
+
+## 3. Switch to the draft
+
+```bash
+picked workspace use --project proj_a1b2 --workspace ws_draft
+```
+
+```
+Active workspace: Checkout rework [DRAFT] in project proj_a1b2 (source: preview)
+Generated types at /app/src/picked-env.d.ts
+```
+
+A command that names **one specific workspace** (draft, live, or archived):
+
+- writes the selection (and its [preview token](/reference/delivery-api/preview-caching-crawling)) to
+  `.picked/settings.json`,
+- switches the resolved `source` to `preview` for that project, and
+- regenerates `picked-env.d.ts` from that workspace's schema (skip with `--no-generate`).
+
+To browse instead, run `picked workspace use` with no flags. The interactive picker lists
+every project, with **Published (live version)** and each of its workspaces.
+
+## 4. See the draft in your app
+
+Both readers of the selection use `.picked/settings.json` with no change to your
+configuration:
+
+- **Type generation** now reads the draft schema. Rerun `picked generate types` after more
+  edits.
+- The **[Vite plugin](/reference/tools/vite-plugin)** reads the draft's configuration and
+  content in development and in a build. It sends the preview token to the
+  [Delivery API](/reference/delivery-api). Restart the dev server to apply a switch.
+
+Your application renders the unpublished draft on your machine, with types.
+
+## 5. Switch back to live
+
+```bash
+picked workspace use --project proj_a1b2
+```
+
+A command that names a project with no `--workspace`, or **Published (live version)** in the
+picker, discards the preview token and returns `source` to `published`. To confirm what is
+active:
+
+```bash
+picked status
+```
+
+```
+Config default: project proj_a1b2 (source: published)
+Active selection: none (using the config default).
+```
+
+## CI and headless runs
+
+`.picked/settings.json` is a local, per-developer file. Do not commit it. To choose one
+workspace in CI with no selection file, set the environment directly:
+
+```bash
+PICKED_PROJECT_ID=proj_a1b2 \
+PICKED_PREVIEW_TOKEN="$DRAFT_TOKEN" \
+  picked generate types --check
+```
+
+`PICKED_PREVIEW_TOKEN` applies only when the resolved `source` is `preview`. See the
+[CLI environment variables](/reference/tools/cli#environment-variables) for the full
+precedence order.
+
+:::note
+A preview token is a long-lived credential for one workspace. Keep it out of the version
+control system, as you do with each other credential. Git ignores `.picked/settings.json`
+for this reason, because `picked workspace use` writes a token there.
+:::
+
+## Related
+
+- [CLI](/reference/tools/cli) — every command and flag.
+- [Workspaces](/reference/dashboard/workspaces) — Live, Draft, and Archived states.
+- [Type generation](/reference/sdk/type-generation) — how the schema becomes types.
+- [Preview, cache, and crawlers](/reference/delivery-api/preview-caching-crawling) — preview tokens on the Delivery API.