@picked/client 0.0.1-dev.1786072899095 → 0.0.1-dev.1786601464574

package/dist/docs/explanation/the-content-model.md

@@ -5,52 +5,61 @@ layout: docs
 
 # About the content model
 
-Picked splits your content into three pieces: a layout, a section, and a content entry.
+Picked splits your content into three pieces: a Model, a Block, and a content entry.
 Why three, when a page editor needs only one?
 
 ## Schema and data are separate
 
-A **layout** is a schema. It sets which fields a piece of content can hold, and it holds
+A **Model** is a schema. It sets which fields a piece of content can hold, and it holds
 no data itself. A **content entry** is one instance of that schema, filled with real
 values.
 
-One layout backs many entries. Describe a campaign page one time, then make many pages
+One Model backs many entries. Describe a campaign page one time, then make many pages
 from it. Each entry carries its own title, its own body, and its own image, but they all
 share the shape.
 
 That split is also what lets your code depend on content that it never saw. Your component
-reads `content.title` because the layout promises a `title`. It works for every entry that
-comes from that layout.
+reads `content.title` because the Model promises a `title`. It works for every entry that
+comes from that Model.
 
-## A layout has a fixed category
+## A category gives a Model a role
 
-Each layout is a **page layout** or a **step layout**, and you choose which when you
-create it. The category cannot change later.
-
-| Layout | It gives shape to | Who renders it |
-| --- | --- | --- |
-| 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. |
+A Model can carry a **category**, and the category decides what the Model gives its shape
+to. A **page layout** backs a standalone Page. A **step layout** backs one Step inside a
+Flow.
 
 The category is fixed because it decides where the SDK renders the entry. That is not a
-property you can change under an entry that exists already. See
-[About pages and flows](/explanation/pages-and-flows).
+property that you can change under an entry that exists already.
+
+A Model can also carry no category. Such a Model has no layout role, and nothing renders
+its entries directly. It holds the content that other content points at, such as a
+product or a category of your own. See
+[About content references](/explanation/content-references).
+
+The three roles are one machine. A layout is a Model with a job in the render path. A
+Model with no category is the same machine with no such job.
 
-## A section is a schema fragment
+## A Block is a schema fragment
 
-A layout gives shape to a whole page or a whole step. A **section** is a part that you put
-inside one or more layouts.
+A Model gives shape to a whole page or a whole step. A **Block** is a part that you put
+inside one or more Models.
 
-Define a hero one time as a section, then point at it from every page layout that needs
-one. Change the section and every layout that holds it changes with it.
+Define a hero one time as a Block, then point at it from every Model that needs one.
+Change the Block and every Model that holds it changes with it.
 
-This is the reason sections exist at all. Without them you must describe a common
-structure again in each layout, and the copies then become different. It is the same
+This is the reason Blocks exist at all. Without them you must describe a common
+structure again in each Model, and the copies then become different. It is the same
 argument for one fact in one place that runs through the rest of this documentation.
 
+A Block sits **inside** the entry that embeds it. It has no entry of its own, and no id
+that you can point at.
+
+That is the difference between a Block and a reference. A Block is a shape that many
+entries hold. A reference is a pointer at one entry that many entries share.
+
 ## Why a schema change does not migrate your data
 
-Change a layout or a section, and Picked does not rewrite the entries behind it. An entry
+Change a Model or a Block, and Picked does not rewrite the entries behind it. An entry
 that no longer matches its schema becomes invalid, and the dashboard shows an error on
 each field that does not fit.
 
@@ -58,20 +67,21 @@ That is deliberate. An automatic change must decide what a new required field ho
 every entry that came before it. Any value that it chooses is content that nobody wrote.
 Picked reports the error instead, and you correct it.
 
-The cost is real. After a schema change, check every entry that uses that layout and fix
+The cost is real. After a schema change, check every entry that uses that Model and fix
 each error before you publish. Picked serves valid content only, so an entry with an error
 does not reach a visitor.
 
 ## An error points at the exact field
 
 A validation error carries a path in JSON style, such as `sections[0].data.title`. The
-path holds through nested groups, repeated fields, and sections. An error inside a
+path holds through nested groups, repeated fields, and Blocks. An error inside a
 repeated group therefore tells you which item in that group holds it.
 
 ## Related
 
-- [Page and step layouts](/reference/dashboard/content/layouts) — every field type.
-- [Sections](/reference/dashboard/content/sections) — the reusable fragments.
+- [Models](/reference/dashboard/content/models) — every field type.
+- [Blocks](/reference/dashboard/content/blocks) — the reusable fragments.
 - [Content entries](/reference/dashboard/content/content-entries) — the editor and the
   validation.
-- [About pages and flows](/explanation/pages-and-flows) — which layout category you need.
+- [About content references](/explanation/content-references) — how one entry points at another.
+- [About pages and flows](/explanation/pages-and-flows) — which category you need.

package/dist/docs/how-to/authenticate-the-cli.md

@@ -0,0 +1,95 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to authenticate the CLI
+
+This guide shows you how to install `@picked/cli` and sign it in. Commands that read your
+organizations, projects, and workspaces then know who you are. It expects a Picked account
+and a project directory to work in.
+
+## 1. Install the CLI
+
+:::code-group
+
+```bash [npm]
+npm install --save-dev @picked/cli
+```
+
+```bash [pnpm]
+pnpm add -D @picked/cli
+```
+
+```bash [yarn]
+yarn add -D @picked/cli
+```
+
+:::
+
+The binary is `picked`. Run it from the directory that holds your `picked.config.ts`, so it
+reads your configuration and writes your selection next to it.
+
+## 2. Sign in
+
+```bash
+picked login
+```
+
+The command opens your browser for a one-time sign-in and prints your identity:
+
+```
+Opening your browser to sign in...
+https://api.picked.app/…/oauth/authorize?…
+Logged in as you@example.com (https://api.picked.app)
+```
+
+The CLI stores the session in `~/.picked/auth/<origin>.json`, outside any repository, with
+file mode `600`. It refreshes the session as it nears expiry.
+
+## 3. Confirm the session
+
+```bash
+picked whoami
+```
+
+```
+you@example.com (https://api.picked.app)
+```
+
+Each command acts on the API origin your current directory resolves to, and on no other. To
+end the session for that origin:
+
+```bash
+picked logout
+```
+
+```
+Logged out of https://api.picked.app.
+```
+
+## Run the CLI in CI
+
+CI has no browser, so give the CLI a token instead of a session. `PICKED_TOKEN` takes
+precedence over any stored session:
+
+```bash
+PICKED_TOKEN="$PICKED_ACCESS_TOKEN" picked generate types --check
+```
+
+If an API deployment does not offer OAuth client registration, `picked login` fails and
+tells you to set `PICKED_TOKEN`. It falls back to no other flow.
+
+:::note
+This is a developer session for local tooling. It is not the same as an
+[API key](/reference/dashboard/api-keys), which authenticates server-to-server delivery and
+management calls, or [dashboard sign-in](/reference/management-api/authentication). Use an
+API key for an application; use `picked login` for the CLI on your machine.
+:::
+
+## Related
+
+- [CLI](/reference/tools/cli) — every command, flag, and environment variable.
+- [How to switch workspaces](/how-to/switch-workspaces) — the draft-preview workflow.
+- [How to create and revoke an API key](/how-to/create-and-revoke-an-api-key) — credentials
+  for applications.

package/dist/docs/how-to/create-a-content-entry.md

@@ -0,0 +1,48 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to create a content entry
+
+This guide shows you how to make one instance of a Model and fill it with data. You need
+a Model first. See [How to define a page layout](/how-to/define-a-page-layout).
+
+A Page makes its own entry when you create the page. Use this guide for the content that
+no Page and no Step owns, such as an author or a product.
+
+## 1. Open the entries list
+
+1. Open your workspace.
+2. Click **CMS** in the sidebar.
+3. Click **Content entries**.
+
+## 2. Create the entry
+
+1. Click **New content**.
+2. Choose the **Model** for the entry.
+3. Fill in each field. The form comes from the schema of the Model.
+4. Click **Create entry**.
+
+The Model is fixed when you create the entry. To move content to another Model, make a
+new entry and copy the values across.
+
+## 3. Correct every error
+
+An invalid field shows an error next to it while you edit. The error carries the path to
+the exact field. Correct each one before you publish, because Picked serves valid content
+only.
+
+## Find an entry again
+
+The entries list shows a title for each entry. The title is the first single-line text
+field of the entry. It shows the entry id when no such field holds a value.
+
+Use the **Model** filter to narrow the list to one Model.
+
+## Related
+
+- [Content entries](/reference/dashboard/content/content-entries) — the editor reference.
+- [Models](/reference/dashboard/content/models) — every field type.
+- [How to point one entry at another](/how-to/point-one-entry-at-another)
+- [How to publish a workspace](/how-to/publish-a-workspace)

package/dist/docs/how-to/define-a-page-layout.md

@@ -5,8 +5,8 @@ layout: docs
 
 # How to define a page layout
 
-This guide shows you how to define the shape of a page. A layout sets which fields a page
-can hold, and it holds no data itself.
+This guide shows you how to define the shape of a page. A page layout sets which fields a
+page can hold, and it holds no data itself.
 
 ## Steps
 
@@ -19,7 +19,7 @@ can hold, and it holds no data itself.
 6. Add your fields. Choose a type for each one.
 7. Click **Create model**.
 
-The category is fixed when you create the layout. You cannot change it later.
+The category is fixed when you create the Model. You cannot change it later.
 
 ## Make a field repeatable
 
@@ -31,9 +31,16 @@ for a gallery, or for a list of features.
 Add a **Group** field to hold a set of fields under one key. Make the group repeatable to
 describe a list of objects, such as a list of feature cards.
 
+## Define content with no layout role
+
+A Model needs no category. Leave **Category** as **None (general content)** for content
+that no Page and no Step renders, such as an author or a product. Reach such a Model
+under **CMS** in the sidebar, and point at its entries with a **Reference** field.
+
 ## Related
 
 - [About the content model](/explanation/the-content-model) — why the schema and the data
   are separate.
-- [Page and step layouts](/reference/dashboard/content/layouts) — every field type.
-- [How to reuse a section](/how-to/reuse-a-section).
+- [Models](/reference/dashboard/content/models) — every field type.
+- [How to reuse a section](/how-to/reuse-a-section)
+- [How to point one entry at another](/how-to/point-one-entry-at-another)

package/dist/docs/how-to/install-the-sdk.md

@@ -22,6 +22,13 @@ npm install @picked/client @picked/svelte effector
 
 :::
 
+:::note
+`picked` is a shorter name for the same client. `npm install picked` gives you
+`createClient` from `picked` and the `picked.config` helpers from `picked/config`. It also
+gives you the `picked` command. npm adds `@picked/client` with it, which is where the
+generated types attach.
+:::
+
 ## 2. Create and start the client
 
 :::code-group

package/dist/docs/how-to/point-one-entry-at-another.md

@@ -0,0 +1,61 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to point one entry at another
+
+This guide shows you how to point one content entry at another, such as a product at its
+category. You need two Models: the one that holds the pointer, and the one that the
+pointer reaches.
+
+## 1. Create the target Model
+
+1. Click **CMS** in the sidebar, then **Models**.
+2. Click **New model**.
+3. Enter a **Name** and a **Key**, such as `category`.
+4. Leave **Category** as **None (general content)**.
+5. Add your fields.
+6. Click **Create model**.
+
+## 2. Add a Reference field
+
+1. Open the Model that holds the pointer.
+2. Drag a **Reference** property onto the schema.
+3. Enter a **Name** and a **Key**, such as `category`.
+4. Set **Target Model** to the Model from step 1.
+5. Click **Save**.
+
+Turn on **repeatable** for a field that points at more than one entry. Leave **Target
+Model** as **Any Model** to accept an entry of any Model in the workspace.
+
+## 3. Choose a target on an entry
+
+1. Open a content entry that uses the Model.
+2. Find your Reference field.
+3. Click **Choose entry**.
+4. Search for the entry.
+5. Choose the entry.
+6. Click **Save**.
+
+Use **Change entry** to point the field somewhere else. Use **Clear** to remove the
+pointer. **Clear** deletes no content.
+
+## Delete a target
+
+Picked does not delete an entry while another entry points at it. Clear the reference on
+each entry that points at the target, then delete the target.
+
+The same rule holds for a Model. Remove the Reference field that holds it as its **Target
+Model** first.
+
+## Read it in your code
+
+The pointer and the entry travel separately. See
+[How to read a referenced entry](/how-to/read-a-referenced-entry).
+
+## Related
+
+- [About content references](/explanation/content-references) — why a reference is a pointer.
+- [Models](/reference/dashboard/content/models) — the field and its options.
+- [Content entries](/reference/dashboard/content/content-entries) — the editor reference.

package/dist/docs/how-to/read-a-referenced-entry.md

@@ -0,0 +1,111 @@
+---
+type: how-to
+layout: docs
+---
+
+# How to read a referenced entry
+
+This guide shows you how to read the content that a
+[Reference field](/reference/dashboard/content/models#reference-fields) points at. You
+need a component that renders a step first. See
+[How to render a step form](/how-to/render-a-step-form).
+
+A Reference field holds a pointer, and not the content. The entry travels beside the
+content of the step, so you resolve the pointer against the content of the client.
+
+## 1. Resolve a single reference
+
+Pass the raw field value to `useReference()` in React, or to `getReference()` in Svelte.
+
+:::code-group
+
+```tsx [React]
+import { useUnit } from 'effector-react'
+import { useReference, useStepContent } from '@picked/react/hooks'
+
+export function ProductCategory() {
+  const content = useStepContent()
+  const category = useUnit(useReference(content?.category))
+
+  if (!category) return null
+
+  return <span>{String(category.data.name ?? '')}</span>
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getStepContent, getReference } from '@picked/svelte/hooks'
+
+  const content = getStepContent()
+  const category = getReference(content.map((c) => c?.category ?? null, { skipVoid: false }))
+</script>
+
+{#if $category}
+  <span>{$category.data.name ?? ''}</span>
+{/if}
+```
+
+:::
+
+In Svelte, pass a store and not a plain value. Content arrives after the component
+starts. A plain value therefore holds the result at "not set".
+
+## 2. Resolve a repeatable reference
+
+Use `useReferences()` or `getReferences()`. They give a list in field order.
+
+:::code-group
+
+```tsx [React]
+import { useUnit } from 'effector-react'
+import { useReferences, useStepContent } from '@picked/react/hooks'
+
+export function ProductCategories() {
+  const content = useStepContent()
+  const categories = useUnit(useReferences(content?.categories))
+
+  return (
+    <ul>
+      {categories.map((category) => (
+        <li key={category.id}>{String(category.data.name ?? '')}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+```svelte [Svelte]
+<script lang="ts">
+  import { getStepContent, getReferences } from '@picked/svelte/hooks'
+
+  const content = getStepContent()
+  const categories = getReferences(content.map((c) => c?.categories ?? null, { skipVoid: false }))
+</script>
+
+<ul>
+  {#each $categories as category (category.id)}
+    <li>{category.data.name ?? ''}</li>
+  {/each}
+</ul>
+```
+
+:::
+
+The list holds no empty places, so you need no check for each item.
+
+## Handle a target that does not resolve
+
+A single reference gives an empty result when Picked cannot resolve the target. A
+repeatable reference leaves the item out of the list.
+
+This happens when somebody deleted the target, when the target belongs to another
+workspace, or when the chain of references is deeper than the limit.
+
+Render something else for the empty case, as the React example above does.
+
+## Related
+
+- [Content](/reference/sdk/content) — every hook and its return type.
+- [About content references](/explanation/content-references) — why the entry travels separately.
+- [How to point one entry at another](/how-to/point-one-entry-at-another) — the dashboard side.

package/dist/docs/how-to/reuse-a-section.md

@@ -6,27 +6,42 @@ layout: docs
 # How to reuse a section
 
 This guide shows you how to define a common structure one time and use it in more than
-one layout.
+one Model.
 
-## Create a section
+## 1. Create the section
 
-1. Open your workspace.
-2. Click **Pages** in the sidebar, then **Sections**.
+1. Click **Pages** in the sidebar.
+2. Click **Page Sections**.
 3. Click **New block**.
 4. Enter a **Name** and a **Key**.
 5. Add your fields.
 6. Click **Create block**.
 
-## Use it in a layout
+The **Category** is **Section** already, because you opened the list from **Page
+Sections**.
+
+## 2. Accept the section in a Model
 
 1. Open a page layout or a step layout.
-2. Add a **Section** field.
-3. Point that field at your section.
+2. Add a **Page Sections** field to the schema.
+3. Click **Save**.
+
+The field now accepts any Block of the Section category. Make the field repeatable to
+build a page from a list of sections.
+
+If you want one section at a fixed place instead of a list, add a **Content block** field.
+Set its **Block category** to the **Section** category.
+
+## 3. Choose the section in an entry
 
-The layout now carries the fields of the section at every place where that field appears.
+1. Open a content entry that uses the Model.
+2. Find the field that you added.
+3. Choose your Block.
+4. Fill in the fields of the Block.
+5. Click **Save**.
 
 :::warning
-An edit to a section does not migrate the entries that use it. Check each affected content
+An edit to a Block does not migrate the entries that use it. Check each affected content
 entry again, and correct every field error before you publish.
 :::
 
@@ -34,4 +49,5 @@ entry again, and correct every field error before you publish.
 
 - [About the content model](/explanation/the-content-model) — why a schema change does not
   migrate your data.
-- [Sections](/reference/dashboard/content/sections) — the reference.
+- [Blocks](/reference/dashboard/content/blocks) — the reference.
+- [Models](/reference/dashboard/content/models) — every field type.

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

@@ -0,0 +1,123 @@
+---
+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`. For CI, set `PICKED_TOKEN` instead — 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_TOKEN="$TOKEN" \
+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.

package/dist/docs/index.md

@@ -25,7 +25,7 @@ Then:
 
 - **[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.
+- **[Content](/how-to/define-a-page-layout)** — Models, Blocks, entries, 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.