picked 0.0.101-next.2 → 0.0.101

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

@@ -0,0 +1,74 @@
+---
+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.
+
+## 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 |
+| --- | --- | --- | --- |
+| Upload a file | [`assetUploadInit`](/reference/management-api/schema/cms-models#assetuploadinit), [`assetCommit`](/reference/management-api/schema/cms-models#assetcommit) | [`init_asset_upload`](/reference/tools/mcp#init_asset_upload), [`commit_asset_upload`](/reference/tools/mcp#commit_asset_upload) | `tools.init_asset_upload({ project_id, file_name, content_type })`, `tools.commit_asset_upload({ project_id, asset_id, version_id, file_name, storage_path })` |
+| List the assets of a project | [`assets`](/reference/management-api/schema/cms-models#assets) | [`list_assets`](/reference/tools/mcp#list_assets) | `tools.list_assets({ project_id })` |
+
+Between the two calls, send the file in a `PUT` request to the URL that the first call gives.
+
+## 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/docs/reference/dashboard/content/blocks.mdx

@@ -0,0 +1,66 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../../components/Screenshot'
+
+# Blocks
+
+A Block is a reusable schema fragment that you embed inside a Model, so that a common structure is defined one time.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/blocks"
+  alt="The blocks list in the schema builder on the Picked dashboard"
+/>
+
+## What a Block is
+
+A Block is a schema fragment with its own **Key**. A
+[Model](/reference/dashboard/content/models) gives its shape to a whole Page or Step. A
+Block is a part that you put into one or more Models. Define the shape one time, then
+reuse it everywhere.
+
+A Block holds no data of its own. The content that fills a Block sits inside the entry
+of the Model that embeds it.
+
+## Where a Block appears
+
+**CMS** in the sidebar holds **Blocks**, and that list shows every Block in the
+workspace. **Pages** holds **Page Sections**, which is the same list limited to the
+Section category.
+
+## Category
+
+| Category | What it does |
+| --- | --- |
+| **Section** | Marks the Block as a page section. A **Page Sections** field accepts it. |
+| **None (general content)** | Gives the Block no layout role. |
+
+The category is fixed when you create the Block. You cannot change it later.
+
+A **Content block** field holds the category of the Blocks that it accepts. Give that
+field the **Section** category to build a page section list.
+
+A field set to **Any category** accepts every Block in the workspace. This is the only
+kind of field that can hold a Block with no category.
+
+## Field types
+
+A Block holds the same field types as a Model. See
+[Field types](/reference/dashboard/content/models#field-types).
+
+## 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 |
+| --- | --- | --- | --- |
+| List the Blocks of a workspace | [`contentBlocks`](/reference/management-api/schema/cms-models#contentblocks) | [`list_content_blocks`](/reference/tools/mcp#list_content_blocks) | `tools.list_content_blocks({ workspace_id })` |
+| Create a Block | [`contentBlockCreate`](/reference/management-api/schema/cms-models#contentblockcreate) | [`create_content_block`](/reference/tools/mcp#create_content_block) | `tools.create_content_block({ workspace_id, name, key, schema })` |
+
+## Related
+
+- [About the content model](/explanation/the-content-model) — why Blocks exist.
+- [How to reuse a section](/how-to/reuse-a-section)
+- [Models](/reference/dashboard/content/models)

package/docs/reference/dashboard/content/content-entries.mdx

@@ -0,0 +1,109 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../../components/Screenshot'
+
+# Content Entries
+
+A content entry is one instance of a Model, filled with real data. A Page renders one entry, and a Flow Step can render one too.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/content"
+  alt="The content entries list on the Picked dashboard"
+/>
+
+## What a content entry is
+
+A content entry is an instance of the schema of a
+[Model](/reference/dashboard/content/models). The Model sets the fields, and the entry
+holds the values. One Model backs many entries, and each entry holds its own data.
+
+The Model of an entry is fixed when you create the entry.
+
+## The entries list
+
+**CMS** in the sidebar holds **Content entries**, with a count of every entry in the
+workspace.
+
+| Column | What it shows |
+| --- | --- |
+| Title | The value of the first single-line text field of the entry. It falls back to the entry id when no such field holds a value. |
+| Model | The Model that the entry belongs to. |
+| Entry ID | The stable id of the entry. |
+| Last updated | When somebody last saved the entry. |
+
+The **Model** filter narrows the list to one Model. The list has no search, because the
+title is derived at read time and is not a column that Picked can search.
+
+## How entries bind to pages and steps
+
+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)
+with a Step Layout binds an entry the same way. When the SDK renders the Page or the
+Step, it resolves the linked entry and gives the data to your component.
+
+## Edit entry data
+
+The entry editor renders a form from the schema of the Model. There is one input for
+each field, in the order that the schema sets. A repeatable field shows as a sortable
+list. You can add to that list and put it into a new order. A group field holds its
+inputs under one heading.
+
+## Reference fields
+
+A [Reference field](/reference/dashboard/content/models#reference-fields) holds a pointer
+at another entry, and not a copy of it.
+
+| Control | What it does |
+| --- | --- |
+| **Choose entry** | Opens the entry picker. |
+| **Change entry** | Opens the entry picker on a field that holds a target already. |
+| **Clear** | Removes the pointer. It does not delete the entry. |
+
+The entry picker lists the entries that the **Target Model** of the field allows, and it
+has a search box. **Open model** opens the Model of an entry in a new tab.
+
+## Validation
+
+Invalid data shows as an error on each field. The error carries a path in the JSON style,
+and it points at the exact place in the entry, for example `sections[0].data.title`.
+
+A reference field reports an error when its target does not exist, or when the target
+belongs to the wrong Model. Fix every error before you publish, because Picked serves
+valid content only.
+
+## Delete rules
+
+Picked does not delete an entry while something still points at it.
+
+| Condition | Result |
+| --- | --- |
+| A Step uses the entry as its layout | The delete stops. |
+| Another entry points at it through a Reference field | The delete stops. |
+
+Clear the reference on the other entry first, then delete the target.
+
+## 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 |
+| --- | --- | --- | --- |
+| List the entries | [`contentEntries`](/reference/management-api/schema/cms-models#contententries) | [`list_content_entries`](/reference/tools/mcp#list_content_entries) | `tools.list_content_entries({ workspace_id, content_model_id })` |
+| Bind an entry to a page or a step | [`stepUpdate`](/reference/management-api/schema/step#stepupdate) | [`update_step`](/reference/tools/mcp#update_step) | `tools.update_step({ step_id, layout_content_entry_id })` |
+| Edit the entry data | [`contentEntryUpdate`](/reference/management-api/schema/cms-models#contententryupdate) | [`update_content_entry`](/reference/tools/mcp#update_content_entry) | `tools.update_content_entry({ content_entry_id, data })` |
+| Find the entries that are not valid | [`workspaceContentEntryValidation`](/reference/management-api/schema/cms-models#workspacecontententryvalidation) | [`validate_workspace_content_entries`](/reference/tools/mcp#validate_workspace_content_entries) | `tools.validate_workspace_content_entries({ workspace_id })` |
+| Delete an entry | [`contentEntryDelete`](/reference/management-api/schema/cms-models#contententrydelete) | [`guide_delete_content_entry`](/reference/tools/mcp#guide_delete_content_entry) | `tools.guide_delete_content_entry({ content_entry_id })` |
+
+The MCP server does not delete an entry. `guide_delete_content_entry` gives the link to the entry in the dashboard, where you delete it.
+
+## Related
+
+- [About the content model](/explanation/the-content-model) — why the schema and the data
+  are separate.
+- [About content references](/explanation/content-references) — why a delete stops.
+- [How to create a content entry](/how-to/create-a-content-entry)
+- [How to point one entry at another](/how-to/point-one-entry-at-another)
+- [Models](/reference/dashboard/content/models)

package/docs/reference/dashboard/content/models.mdx

@@ -0,0 +1,119 @@
+---
+type: reference
+layout: docs
+---
+
+import { Screenshot } from '../../../../../components/Screenshot'
+
+# Models
+
+A Model is a reusable schema. It sets which fields a piece of content can hold, and it holds no data itself.
+
+<Screenshot
+  route="/{orgSlug}/{projectId}/workspaces/{workspaceId}/models"
+  alt="The models list in the schema builder on the Picked dashboard"
+/>
+
+## Where a Model appears
+
+**CMS** in the sidebar holds **Models**, and that list shows every Model in the
+workspace. The list shows the **Key** below the name, because the key is the value that
+a schema holds.
+
+Two shortcuts open a filtered subset of the same list. **Flows** holds **Step Layouts**,
+and **Pages** holds **Page Layouts**.
+
+## Category
+
+A category gives a Model a role. It decides where the Model appears, and what renders an
+entry that comes from it.
+
+| Category | It gives its shape to | What 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. |
+| **None (general content)** | Content with no layout role. | Nothing renders it directly. A [reference field](#reference-fields) reaches it. |
+
+A Model with no category holds content that other content points at, such as a product
+or a category. It appears under **CMS** only.
+
+:::warning
+The category is fixed when you create the Model. You cannot change it later.
+:::
+
+## Field types
+
+A Model is built from fields. Each field has a type. The type decides the editor for the
+field, and the shape of the value that the field holds.
+
+| Type | Holds | Use it for |
+| --- | --- | --- |
+| **Single line text** | A short string. | A title, a label, or a short headline. |
+| **Multi-line text** | A longer plain string. | A description, or a paragraph with no format marks. |
+| **Markdown** | A Markdown string. | Body copy with format marks. |
+| **Slug** | A URL-safe string. | A part of a path, or an identifier. |
+| **Number** | A numeric value. | A price, a count, or a rating. |
+| **Boolean** | A true or false value. | A toggle or a flag. |
+| **Date** | A date value. | A publish date or a deadline. |
+| **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 Model. | A set of related fields, held together. |
+| **Content block** | A [Block](/reference/dashboard/content/blocks) schema inside the Model. | A shared schema fragment that you reuse. |
+| **Page Sections** | A repeatable Content block field, limited to the Section category. | The section list of a page. |
+| **Reference** | A pointer at another [content entry](/reference/dashboard/content/content-entries). | A product that points at its category. |
+| **Asset** | A link to an [Asset Library](/reference/dashboard/content/asset-library) item. | An image, a video, or a document. |
+| **HTML** | A link to a `.html` file in your library. | HTML that you wrote before, held inside the content. |
+
+## Reference fields
+
+A **Reference** field points at another content entry. The entry that you point at keeps
+its own data, and many fields can point at the same entry.
+
+| Option | Values | What it does |
+| --- | --- | --- |
+| **Target Model** | A Model, or **Any Model** | Limits which entries an editor can choose. |
+| **Repeatable** | On or off | On gives an ordered list of entries. Off gives one entry. |
+
+**Target Model** holds the `key` of the Model, and not its id. A duplicate of the
+workspace therefore keeps the constraint.
+
+A reference stays inside one workspace. A field cannot point at an entry in another
+workspace, and Picked reports such a target as unknown.
+
+## Repeatable and grouped fields
+
+You can make any field **repeatable**. It then shows as a sortable list of values, and
+not as one value. Use it for a gallery, for a list of features, or for any collection.
+
+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.
+
+## Delete rules
+
+Picked does not delete a Model while something still needs it.
+
+| Condition | Result |
+| --- | --- |
+| Content entries still belong to the Model | The delete stops. |
+| A Reference field still holds the Model as its **Target Model** | The delete stops. |
+
+## 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 |
+| --- | --- | --- | --- |
+| List the Models of a workspace | [`contentModels`](/reference/management-api/schema/cms-models#contentmodels) | [`list_content_models`](/reference/tools/mcp#list_content_models) | `tools.list_content_models({ workspace_id })` |
+| Create a Model | [`contentModelCreate`](/reference/management-api/schema/cms-models#contentmodelcreate) | [`create_content_model`](/reference/tools/mcp#create_content_model) | `tools.create_content_model({ workspace_id, name, key, schema })` |
+| Change the fields of a Model | [`contentModelUpdate`](/reference/management-api/schema/cms-models#contentmodelupdate) | [`update_content_model`](/reference/tools/mcp#update_content_model) | `tools.update_content_model({ content_model_id, schema })` |
+| Delete a Model | [`contentModelDelete`](/reference/management-api/schema/cms-models#contentmodeldelete) | None | None |
+
+## Related
+
+- [About the content model](/explanation/the-content-model) — why a schema change does not
+  migrate your data.
+- [About content references](/explanation/content-references) — why a reference is a pointer.
+- [How to define a page layout](/how-to/define-a-page-layout)
+- [How to create a content entry](/how-to/create-a-content-entry)
+- [How to point one entry at another](/how-to/point-one-entry-at-another)
+- [Blocks](/reference/dashboard/content/blocks)

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

@@ -0,0 +1,72 @@
+---
+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.
+
+## Status
+
+The **Settings** tab has a status control. It has two values.
+
+| Value | Effect |
+| --- | --- |
+| **Active** | Picked serves the page to everyone. |
+| **Draft** | Picked keeps the page out of the published site. |
+
+A draft page is absent from the published payload. Picked also holds back the
+steps, fields and actions that only that page uses, and it does not serve the
+page content. A visitor and a search-engine crawler receive nothing.
+
+To see a draft page, open it with a preview link. See
+[How to see a preview of a workspace](/how-to/preview-a-workspace). One preview
+link opens every draft page in the workspace.
+
+Status applies to Flows and to Pages. It is not the same as the status of the
+workspace: a draft page can be in a live workspace.
+
+:::warning
+Status is part of the published version. Change the value, then publish the
+workspace to apply the change to the live site.
+:::
+
+## Change or remove the layout
+
+Use the change-layout control on the **Settings** tab to move the page to another
+[Page Layout](/reference/dashboard/content/models#category). 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.
+
+## 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 |
+| --- | --- | --- | --- |
+| Edit the page content | [`contentEntryUpdate`](/reference/management-api/schema/cms-models#contententryupdate) | [`update_content_entry`](/reference/tools/mcp#update_content_entry) | `tools.update_content_entry({ content_entry_id, data })` |
+| Set the status | [`experienceUpdate`](/reference/management-api/schema/experience#experienceupdate) | [`update_experience_flow`](/reference/tools/mcp#update_experience_flow) | `tools.update_experience_flow({ experience_id, workspace_id, status })` |
+| See a draft page | None | [`get_preview_url`](/reference/tools/mcp#get_preview_url) | `tools.get_preview_url({ workspace_id, target_url })` |
+| Change the layout | [`stepUpdate`](/reference/management-api/schema/step#stepupdate) | [`update_step`](/reference/tools/mcp#update_step) | `tools.update_step({ step_id, layout_content_entry_id })` |
+
+## 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)
+- [Models](/reference/dashboard/content/models) — the schema behind a Page.

package/docs/reference/dashboard/experiences.mdx

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