@picked/client 0.0.1-dev.1789541668638 → 0.0.1-next.1

package/dist/docs/explanation/conditions-and-the-logic-engine.md

@@ -1,94 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About conditions and the logic engine
-
-A condition decides whether a visitor sees something. One rule format covers every one of
-those decisions, both in the dashboard and in code. This page covers why there is one
-engine, and what it can reach.
-
-## One rule format, many places
-
-The dashboard uses the visual condition builder in four places, and the SDK evaluates the
-same rules in each:
-
-- **Condition nodes** decide which branch a flow takes.
-- **Experience conditions** decide whether an experience starts for a visitor.
-- **Initialize-open conditions** decide whether an experience opens by itself.
-- **Field option conditions** show or hide one option in a field.
-
-One format means one model to learn. Learn how a rule reads in the flow builder, and you
-can read the rule that gates an experience.
-
-## What a rule looks like below
-
-A rule is JSON Logic. The visual builder writes it for you, and you can also write it
-directly in SDK code:
-
-```ts
-{
-  '==': [{ var: 'responses.country' }, 'US']
-}
-```
-
-Rules sit in groups, and each group is an **AND** or an **OR**. Put a group inside another
-group to build a larger rule.
-
-The format is data, and not code. That is the point. A rule travels from the dashboard to
-the browser inside the published snapshot. A function cannot travel that way.
-
-## What a rule can read
-
-| Source | What it holds |
-| --- | --- |
-| **Responses** | The values your visitors send through the fields of the current experience. |
-| **Actions** | The actions that ran during the flow. |
-| **Feature flags** | Whether Picked allocates this visitor to a flag. |
-| **Location** | The parts of the current URL: pathname, search parameters, hostname, and hash. |
-
-Each one is state the SDK already holds, which is why a rule evaluates without a network
-request.
-
-## Predicates are the escape hatch
-
-The four sources above cover what Picked knows. They do not cover what *your application*
-knows: a cart total, an account level, or the profile of a signed-in user.
-
-A **predicate** gives you that. It is a function that you register on the client, and a
-rule invokes it by name:
-
-```ts
-{ invoke: { var: 'predicates.has-items-in-cart' } }
-```
-
-The predicate receives a frozen state snapshot and returns a boolean, a string, an array
-of strings, or `undefined`. Because a rule can invoke one, the visual builder in the
-dashboard reaches your application data, and nobody writes JSON Logic by hand.
-
-A predicate must stay pure and fast. The SDK can invoke it many times while it evaluates a
-flow, and everything that waits on the rule waits on the predicate.
-
-## Why a precondition is not a condition
-
-The client takes two gates, and they answer different questions:
-
-| Gate | Question |
-| --- | --- |
-| Precondition | Must Picked start at all? |
-| Condition | Is this visitor eligible? |
-
-A precondition runs at startup, and that has a result which catches people out. A
-precondition that points at a feature flag reads the bucket of that flag, and a read is
-what allocates the visitor. Every visitor is therefore allocated to that flag before
-anything else happens, and that includes a visitor who never reaches the experience the
-flag controls. See
-[About feature flag allocation](/explanation/feature-flag-allocation).
-
-## Related
-
-- [Condition builder](/reference/dashboard/flow-builder/condition-builder) — the visual
-  editor.
-- [SDK conditions](/reference/sdk/conditions) — the JSON Logic shapes.
-- [Predicates](/reference/sdk/predicates) — the state snapshot and the return types.

package/dist/docs/explanation/content-references.md

@@ -1,99 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About content references
-
-A [Reference field](/reference/dashboard/content/models#reference-fields) points one
-content entry at another. Why a pointer, when Picked can put the content into the entry
-that needs it?
-
-## A pointer keeps one fact in one place
-
-A product points at its category. Ten products can point at the same category.
-
-A copy makes ten categories. Correct the name of the category and you must correct it ten
-times. The copy that you do not correct is now wrong.
-
-A pointer makes one category. Correct the name one time, and every product that points at
-it is correct.
-
-This is the same reason that Blocks exist, one level up. A Block shares a *shape* between
-entries. A reference shares an *entry* between entries.
-
-## The target travels beside the content
-
-Picked sends the entries of your steps in `content`. It sends the entries that a
-reference reaches in `references`. Both go into the same content index in the SDK, keyed
-by the id.
-
-Picked can put the target inside the field instead, and it did so before. Three things
-count against that.
-
-A shared target costs one blob, and not one blob for each entry that points at it. Ten
-products with the same category send the category one time.
-
-A separate entry has an id. Your code reads it with `useContent(id)`, and live preview
-updates it while you edit. A target inside a field has no id, so an update finds nothing
-to change.
-
-The reader chooses how deep to go. A component that shows a category reads the category.
-A component that shows a card reads the product only, and it costs nothing more.
-
-## Picked stops a chain at a depth of five
-
-Content can point at content that points at content. Such a chain has no end of its own.
-A cycle has none at all. Two entries that point at each other keep the chain open for as
-long as something asks.
-
-Picked therefore resolves a chain to a depth of five. It counts the depth from the
-entries that your steps point at. It also keeps the entries that it saw, so that a cycle
-stops.
-
-Five is a choice, and not a rule of the system. It is deep enough for the shapes that
-content takes, such as a product, its category, and the owner of that category. It is
-also small enough that one page cannot pull a whole workspace over the wire.
-
-## A missing entry is how Picked says "no such entry"
-
-Picked sends no blob for a pointer whose target it cannot resolve. The entry is absent
-from `references`.
-
-The other option is a blob with no data. That reads as an entry that exists and is empty,
-which is a different fact from an entry that is not there.
-
-Your code cannot tell one from the other. The empty record also goes into the content
-index under an id that resolves. A missing entry looks like nothing else.
-
-## A delete stops while a reference is live
-
-Picked does not delete an entry that another entry points at. It does not delete a Model
-that a Reference field holds as its target.
-
-The other option is a pointer at nothing. Picked must then choose what the field holds,
-and every answer is wrong. It can give your component an empty value that the component
-does not expect. It can also remove content that somebody wrote, with no report.
-
-A stop costs you one step. Clear the reference, then delete the target. In return, a
-field that holds a pointer always points at something that exists.
-
-## A reference stays inside its workspace
-
-A field cannot point at an entry in another workspace. Picked reports such a target as
-unknown.
-
-A workspace is one version of the configuration of a project, and you publish it whole. A
-pointer that leaves the workspace resolves against content that this workspace never
-sent. The two sides can then go live at different times.
-
-The delivery surface applies the same rule on a read, so a target outside the workspace
-never reaches a visitor.
-
-## Related
-
-- [Models](/reference/dashboard/content/models) — the field and its options.
-- [Content entries](/reference/dashboard/content/content-entries) — the editor and the delete rules.
-- [Content](/reference/sdk/content) — how your code resolves a pointer.
-- [Experience content endpoint](/reference/delivery-api/experience-content) — the wire shape.
-- [About the content model](/explanation/the-content-model) — why a schema and its data are separate.

package/dist/docs/explanation/feature-flag-allocation.md

@@ -1,218 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About feature flag allocation
-
-When does a visitor enter a test, and what decides the group they land in? The answer is
-not "when you create the feature flag" and not "when the page loads". It is the moment something
-reads the bucket, and that moment is yours to choose.
-
-## A registration is not a decision
-
-The SDK loads every feature flag in your project at startup. It allocates nobody then. A feature flag
-stays undecided until something reads its bucket. The first read runs the `decide`
-function, stores the result, and reports the decision.
-
-You therefore choose when Picked commits a visitor to a feature flag. You choose it by the point
-at which you read the feature flag.
-
-## A read of the bucket records an exposure
-
-The first read is the decision, so it is also the moment the visitor enters the test. If
-you read every feature flag at startup, every visitor counts as exposed to every test. That
-includes a test the visitor never reached.
-
-Read a feature flag where the decision matters: after the cart loads, after the quote returns, or
-after you know who the visitor is. A feature flag that you read before that point puts a visitor in
-a test they never saw, and the uplift number then means nothing.
-
-## A condition reads the bucket, so a condition allocates
-
-Most reads are not calls that you write. They come from a condition. A condition that
-points at a feature flag with `invoke: { var: 'features.<id>' }` must have the bucket
-before it can compare it. That read allocates the visitor, exactly as a call in your own
-code does.
-
-Where the condition sits therefore decides who enters the test:
-
-| The condition is | It runs | Who enters the test |
-| --- | --- | --- |
-| An experience condition | When Picked evaluates that experience | Only a visitor who reaches the experience |
-| A precondition | At startup, before anything else | Every visitor who loads the page |
-
-A precondition that points at a feature flag allocates every visitor on your site, and it
-does so before the visitor sees anything. Keep a feature flag out of a precondition unless
-it truly controls whether Picked starts at all.
-
-Keep each `decide` function fast for the same reason. Everything that waits for the
-condition waits for `decide`, and that includes the experience itself. A network call
-inside `decide` delays what the visitor sees.
-
-## How Picked chooses
-
-For a feature flag you control from the dashboard the choice is deterministic. Picked
-gives each visitor a stable value for each feature flag. It derives that value from the
-visitor ID and from the ID of the feature flag, and it compares the value against the
-weight. Picked allocates the visitor when the value is below the weight.
-
-The same visitor gets the same result for one feature flag on every visit, while the
-weight stays the same.
-
-That is also why a feature flag you control from the dashboard cannot use the data of
-your application in its decision. The value comes from the visitor ID, the feature flag
-ID, and the weight, and from nothing else. Define the feature flag in SDK code when the
-decision needs a cart, a quote, or a profile.
-
-## More than two groups
-
-A Text feature flag has a table of variants, and each variant is one group. Picked
-allocates a visitor to exactly one of them, and the control group is one of the rows.
-
-The two types decide by different routes, and the difference matters if you compare them:
-
-| Type | Picked compares | Against |
-| --- | --- | --- |
-| Boolean | The stable value of the visitor, out of 100 | The weight |
-| Text | One stable value for each variant | The weight of that variant |
-
-A Text feature flag gives each variant a score. Picked makes the score from the visitor
-ID, the feature flag ID, and the key of the variant. The weight of the variant then scales
-that score. The variant with the best score receives the visitor.
-
-The weight of a variant therefore changes the score of that variant alone. No other
-variant moves because of it.
-
-A Boolean feature flag makes the same comparison it always has. A feature flag that you
-made before variants existed therefore keeps every visitor where it put them.
-
-Picked derives the stable value from the visitor ID and from the ID of the feature flag,
-for both types. The two types are therefore independent of each other in the same way that
-two feature flags are.
-
-**The order of the rows has no effect.** Picked scores each variant from its key, and the
-key of a variant never changes. Move a row in the dashboard and the
-visitors stay where they are. The order that you see is the order that you chose to read
-them in, and nothing more.
-
-Rename a variant and nothing changes. The name travels no further than the dashboard.
-
-Change the string that a variant serves and the visitors stay in the same group, but your
-site and your reports receive the new string. A visitor with a decision in browser storage
-keeps the old string until you increment the version.
-
-## Each feature flag is independent
-
-Picked builds that value from the visitor ID together with the ID of the feature flag.
-Each feature flag therefore gets its own value, and tests that run at the same time are
-independent of each other.
-
-Two feature flags, both at weight 50, split your visitors into four equal parts:
-allocated to both, to one, to the other, or to neither. Three feature flags at weight 50
-give eight groups of 12.5%. Add a feature flag and the groups divide again.
-
-This is what lets you read two experiments separately. Give every feature flag the same
-value, and two feature flags at weight 50 hold exactly the same visitors. Your analytics
-then never sees the mixed groups that tell one result from the other.
-
-## The allocation ratchets
-
-The ratchet applies to both types of feature flag. Inside one feature flag, a larger
-weight only adds visitors. Everybody allocated at
-weight 30 is still allocated at weight 50. The allocation is a **ratchet**: it turns one
-way, and a larger weight never moves a visitor back out.
-
-That property is what makes a staged release safe. A visitor who sees the change at 10%
-still sees it at 20%. A smaller weight is the reverse turn. It removes visitors from the
-top of the range, and every visitor below the new weight keeps what they had.
-
-A Text feature flag has the same ratchet, one variant at a time. A larger weight on one variant only
-adds visitors to that variant. A smaller weight only removes them. Two variants that you
-do not change never exchange visitors with each other.
-
-## A disabled feature flag records nothing
-
-A disabled feature flag allocates nobody, and the difference from a weight of 0
-matters for your reports. At weight 0 the visitor is in the test, and in the
-control group. When the feature flag is disabled, the visitor is not in the test at all.
-
-The SDK does not evaluate a disabled feature flag. It writes no decision to browser
-storage and it reports no decision. The feature flag is also absent from the feature
-list on every analytics event. Expect a step change in your reports when you disable
-one: fewer feature flags for each visitor, and fewer decision events.
-
-This state is temporary. A visitor allocated before you disabled the feature flag keeps
-that bucket in the browser. When you enable the feature flag again, that visitor continues
-in the same group.
-
-## What a version does, and what it does not
-
-Each feature flag carries a version, and it starts at 1. The SDK caches the bucket in
-browser storage under a key that holds the feature flag ID and the version. A visitor
-therefore keeps the same bucket across page loads.
-
-Change a weight and leave the version as it is, and that cache decides the result. A
-visitor who has a cached bucket keeps it. The new weight reaches only a visitor who has no
-cache. Your reports then hold two groups of visitors at the same time, one measured
-against the old weight and one against the new.
-
-Increment the version and the old cache key no longer matches. The feature flag counts as
-undecided, `decide` runs again on the next page load, and every visitor is measured
-against the new weight. Increment it after each weight change, unless you intend the
-change to reach new visitors only.
-
-**The version affects the cache only. It is not part of the allocation.** The ratchet
-still holds after you increment the version: a visitor allocated at weight 30 is allocated
-again at weight 50. You cannot decrement a version.
-
-## When the SDK reports a decision
-
-The SDK sends `feature_decide` the first time that it allocates a visitor to a bucket,
-and only then. On a later page load it restores that bucket from browser storage and sends
-nothing. A visitor who returns therefore produces no `feature_decide` event, although that
-visitor is still in the group they went into the first time.
-
-An integration that listens only for `feature_decide` under-reports every visitor who
-returns. Choose the source that matches your question:
-
-| Question | Source |
-| --- | --- |
-| Which bucket is this visitor in now? | [`client.features.listStore`](/how-to/read-a-feature-flag#1-choose-an-accessor) |
-| Did the SDK allocate a visitor now? | [`feature_decide` on `client.eventBus`](/reference/sdk/features#watch-for-feature-flag-decisions) |
-| Which allocations happened before I subscribed? | [`client.events`](/reference/sdk/features#read-the-events-that-already-happened) |
-
-`listStore` updates each time that a feature flag resolves. It does this whether the SDK
-restored the bucket from storage or allocated the visitor now. A watch on it therefore
-always gives the current state.
-Use `feature_decide` only when you need to know that Picked allocated a visitor at that
-moment.
-
-## What Picked reports for you
-
-Every Picked analytics event carries a `feature_list` context, and a report of your own
-can use it. The context describes each feature flag that this visitor resolved: the
-feature flag ID, the name, the version key, and the bucket. Only a resolved feature flag
-appears there, so the context shows what the visitor was exposed to at the time when the
-event fired.
-
-The optional [Sentry plugin](https://www.npmjs.com/package/@picked/sentry) also tags each
-allocation onto the Sentry scope as `picked.feature.<id>`, with the bucket as the value.
-You can then filter your errors by the variant.
-
-## Preview mode
-
-In preview mode the SDK stores the bucket in session storage and not in local storage. The
-bucket does not stay after you close the tab, and Picked can allocate a preview visitor
-differently from a production visitor. Treat a preview allocation as disposable.
-
-A feature flag that you define in SDK code can ask for the same thing in production with
-`storage: 'session'`. Use it for a short test that must not last across browser sessions.
-
-## Related
-
-- [How to read a feature flag](/how-to/read-a-feature-flag) — the accessors, and which
-  ones resolve the feature flag.
-- [Feature flags](/reference/dashboard/features) — the dashboard controls.
-- [SDK feature flags](/reference/sdk/features) — the definition shape and the accessor
-  table.

package/dist/docs/explanation/how-picked-works.md

@@ -1,124 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About how Picked works
-
-What happens between the moment an editor clicks **Publish** and the moment a visitor
-sees the result? This page follows one change through the whole system.
-
-## The shape of it
-
-Picked splits into two parts that meet at a published snapshot.
-
-```
-Author (dashboard) -> Publish -> Delivery API (config + content)
-  -> SDK reads it -> conditions decide -> component renders
-```
-
-On the left, an editor works in a workspace. Nothing they do reaches a visitor. On the
-right, the SDK in your application reads what was published and renders it. The snapshot
-between them is immutable, so each part moves at its own speed. An editor publishes with
-no deployment, and you deploy with no change to the content.
-
-## What happens when you publish
-
-Picked takes the current workspace and makes an immutable snapshot of it. The result is a
-version, and a project serves exactly one version at a time, the live one. Nothing in a
-published version can change later. A roll-back moves the live pointer of the project to
-an earlier version, and it changes no data.
-
-That is why the dashboard has a draft state at all. The workspace holds the work that is
-still in progress. The version holds what your visitors get.
-
-## What the SDK does at startup
-
-`createClient()` builds the client, and `client.start()` runs it. Between those two calls
-nothing happens yet.
-
-1. **Options resolve.** The dynamic experiences plugin reads the configuration of your
-   project from the source that its `mode` names. That is the data in your bundle, or a
-   request to the Delivery API. A preview token replaces both.
-2. **Everything registers.** The plugin registers every feature flag, condition, field,
-   step, and experience from that configuration. You declare none of them in code.
-3. **Preconditions run.** A precondition asks whether Picked should start at all. A
-   condition asks whether this visitor is eligible.
-4. **Experiences resolve.** Each experience evaluates its condition and looks for its
-   target element in the page.
-5. **Components render.** An experience whose condition is true, and whose target exists,
-   renders the component you registered under its component name.
-
-Step 1 is why the [Vite plugin](/reference/tools/vite-plugin) exists: it embeds the
-options at build time, so production makes no request at startup.
-
-## Why the browser and the server can read from different places
-
-The two ends of a server-rendered page want different things. Your server wants a new
-version to reach visitors at once. That needs a request to the API. The browser wants no
-request at all. That needs the data in your bundle.
-
-The `mode` option belongs to one end only, so you can have both. Give `'api'` to your
-server and `'bundle'` to your browser.
-
-Each end stays consistent with itself. The configuration and the content that one end
-reads always come from the same source. Picked gives them the same version.
-
-The two ends can still hold different versions. An editor publishes a workspace between
-your build and the request, which moves the server to a newer version than the bundle.
-The snapshot from the server then wins. The browser keeps it, and drops the configuration
-that it read.
-
-The reason is that the server made the page from that snapshot. To register a different
-configuration over the top makes the page and the client show different data. One
-version behind is the safer of the two results. The client records the two version IDs on
-`client.versionSkew`, and the [devtools](/reference/tools/chrome-extension) show them.
-
-## Why the flow is a graph
-
-An experience is not a list of screens. It is a directed graph, and the SDK walks it.
-
-The origin node is the entry point. From there each edge leads to a step, an action, or a
-condition. A step waits for the visitor. An action runs a side effect and does not
-interrupt them. A condition evaluates a rule and sends the flow down one of two paths.
-
-The walk is what makes a branch cost so little. To show a different screen to a different
-visitor you add a condition node, and not a second copy of the flow. The same step can
-appear in several flows, because a step belongs to the project and the graph only
-points at it.
-
-## How an action decides which way to go
-
-An action node can carry a success branch and a failure branch, and the SDK picks between
-them from the outcome of your handler:
-
-- The handler **throws**, or its promise rejects: the flow takes the failure branch.
-- The handler **resolves** to any value at all, and that includes `false`: the flow takes
-  the success branch.
-
-This difference matters more than it looks. A valid negative result is not a failure. An
-endpoint that answers `200` with `{ serviced: false }` succeeded — it told you something
-true. Record that value as a response and branch on it with a condition. Keep the failure
-branch for a request that did not complete.
-
-Get this wrong and your failure branch holds two different things at once: a network
-error, and a visitor who lives outside your service area.
-
-## Where content comes in
-
-A flow renders in the browser. A page renders on your server, from content held in the
-Picked CMS, so a search engine reads it in the first response. Both are experiences, and
-both go through the same publish.
-
-The difference is only the place where each one renders, and that follows from what the
-content is for. See [About pages and flows](/explanation/pages-and-flows) and
-[About server-side rendering](/explanation/why-server-side-rendering).
-
-## Related
-
-- [Add Picked to your application](/tutorials/first-experience) — the whole path, in
-  practice.
-- [About workspaces and versions](/explanation/workspaces-and-versions) — draft, live,
-  and roll-back.
-- [Delivery API](/reference/delivery-api) — what the published snapshot looks like on the
-  wire.

package/dist/docs/explanation/how-pickedql-works.md

@@ -1,76 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About PickedQL
-
-PickedQL is SQL over your Picked analytics data, but it is not only SQL. It expands what
-you write before it runs. Why add a layer at all, and not give you the tables?
-
-## The problem it answers
-
-An A/B test question is short to ask, and the SQL behind it is not. Take one question:
-"How many users are in the control group?" It needs four things. It needs a filter on the
-variant, a count of distinct users, a join to each dimension in the group, and a tenant
-filter.
-
-Write that by hand for every question, and most of each query is the same text again.
-
-PickedQL lets you write the short version:
-
-```sql
-SELECT control_users(), variant_users()
-FROM metrics
-WHERE project_id = 'your-project-id'
-```
-
-## What it expands
-
-**Virtual tables.** A name such as `metrics` maps to the real tables below it. You name
-the thing that you ask about, and not the storage.
-
-**Virtual functions.** `control_users()` expands to a full aggregate expression. The
-definition lives in one place, so every report that counts control users counts them the
-same way.
-
-**Automatic joins.** Point at a dimension column such as `device_category` or
-`country_code` and PickedQL adds the `LEFT JOIN` for you. This gives you the most: a
-dimension that you did not join is the most common reason for a wrong answer that looks
-correct.
-
-**SQL passthrough.** Standard SQL still works next to a virtual function, and that
-includes `CASE WHEN`, window functions, and subqueries. The layer adds; it does not
-restrict.
-
-## Why every query must carry a tenant filter
-
-Every query must carry a tenant filter in its `WHERE` clause. That filter is `project_id`
-for most tables. The `projects` table uses `id` instead, because there the row ID *is* the
-project ID.
-
-PickedQL reads that filter and checks your permission for that project. The filter is
-therefore not a convention that you can forget. Without one, the query does not run.
-The isolation is a property of the language, and not of each author.
-
-## Which table to reach for
-
-| Table | Use it for |
-| --- | --- |
-| `metrics` | A dashboard. The data is aggregated first, so it is much faster than raw events. |
-| `events` | Anything deeper. Raw events let you build any breakdown or funnel. |
-| `experience_journey` | A sankey or a funnel chart. One line of SQL returns `source, target, users`. |
-
-Note what `experience_journey` does for you. It builds the eight common table expressions
-that a path analysis needs. Those remove the duplicates, rank the top paths, and call
-`lagInFrame`. You pass your parameters in the `WHERE` clause.
-
-Some reference columns are free on `events`. `step_title`, `experience_title`, and
-`project_name` come from reference tables that PickedQL joins for you.
-
-## Related
-
-- [PickedQL](/reference/pickedql) — the language surface.
-- [Data sources](/reference/pickedql/data-sources) — every table.
-- [Virtual functions](/reference/pickedql/virtual-functions) — every function.
-- [How to run an analytics query](/how-to/analytics) — worked examples.

package/dist/docs/explanation/pages-and-flows.md

@@ -1,64 +0,0 @@
----
-type: explanation
-layout: docs
----
-
-# About pages and flows
-
-An experience has two kinds, and the dashboard makes you choose
-between them when you create one. Why two, and how do you know which one a piece of work needs?
-
-## The two kinds
-
-| | Page | Flow |
-| --- | --- | --- |
-| What it is | A standalone experience that your server renders from a content entry. | An interactive experience of more than one step, which the browser renders. |
-| Use it for | A landing page or a campaign page where the search rank matters. | A quiz, a survey, a product finder, onboarding of more than one step. |
-
-The split is not about how complex the content is. It is about **who has to read it**.
-
-## Why the split exists
-
-A crawler and a social preview read the HTML your server returns. Neither waits for
-JavaScript in the browser. Content that a search engine must find is therefore
-content that must be in the first response. Only a server render puts it there.
-
-A flow has the reverse constraint. Its value is in the interaction: a visitor answers,
-the flow branches, the next screen depends on what came before. None of that can be in the
-first response, because none of it exists until the visitor acts.
-
-Choose a Page when the content must reach a search engine. Choose a Flow when the value is
-in the interaction and a browser render is acceptable.
-
-## What backs a page
-
-Four pieces sit behind every Page, and they are separate on purpose:
-
-1. A **page layout** sets the shape: which fields the page can hold.
-2. A **content entry** fills that shape with real data.
-3. A **Page** binds one entry, so the SDK can render it.
-4. The **SDK** reads the entry and renders it on your server.
-
-Layout and entry are separate because one layout backs many entries. Describe a campaign
-page one time, then make many pages from it. Change the layout and you must check every
-entry again. That is why the dashboard reports an invalid entry and does not serve it.
-
-A step layout does the same thing for one step inside a flow. The parts behave the same
-way. Only the thing that they give shape to is different.
-
-## They meet at the same publish
-
-Both kinds are experiences. Both live in a workspace, both go into the same immutable
-version, and both come out of the same Delivery API. The SDK decides where to render each
-one, and every step before that treats them the same way.
-
-This matters, because it means a project mixes them freely. A server-rendered
-landing page can carry a browser-rendered quiz inside it.
-
-## Related
-
-- [About how Picked works](/explanation/how-picked-works) — the path that both kinds take.
-- [About server-side rendering](/explanation/why-server-side-rendering) — how a Page
-  reaches the browser.
-- [Pages](/reference/dashboard/content/pages) — the page editor.
-- [Experiences](/reference/dashboard/experiences) — the flow options.