@bettercms-ai/mcp 0.83.0 → 0.83.2

package/dist/skills/bettercms/references/components.md

@@ -1,415 +1,415 @@
----
-title: "Components, props and variants"
-description: "The prop contract, instances, sectionType families and variants, publishing codes, rendering components in a site, preview source and component groups."
----
-
-# Components, props and section variants
-
-Doctrine (components vs collections, section anatomy, variants): §3 and §4 of
-`bettercms://playbook/schema`; flows: `new_component` prompt, `componentize_site` prompt. This
-reference is what the code does with what you write. Componentizing a derived site end to end:
-[componentize.md](componentize.md).
-
-## Contents
-
-- [1. The prop contract](#1-the-prop-contract) · [2. Instances](#2-instances) ·
-  [3. Sections, families and variants](#3-sections-families-and-variants) ·
-  [4. Publishing](#4-publishing) · [5. Rendering components in your site](#5-rendering-components-in-your-site)
-- [6. Preview source](#6-preview-source) · [7. The values popover](#7-the-values-popover-dashboard) ·
-  [8. Groups](#8-groups) · [9. Verify](#9-verify)
-
-## 1. The prop contract
-
-A component declares `props`. Each prop is `{ key, label, type, target: { blockId, path },
-defaultValue? }`.
-
-- `type` is one of exactly 30: `text`, `richtext`, `image`, `url`, `boolean`, `number`, `select`, `group`, `table`, `slot`,
-  `form`, then `date`, `color`, `file`, `link`, `icon`, `multiselect` and `button`, then `object`, `datetime`, `slug`,
-  `email`, `phone`, `json`, `location`, `tags`, `rating`, `code`, `reference` and `multi-reference`.
-- The last seven store what the same-named model field stores: `date` is `YYYY-MM-DD`, `color` a
-  hex, `file` `{ url, name?, size? }`, `link` an href string or `{ href, rel?, newTab? }`, `icon` an icon name or an image
-  value, `multiselect` a `string[]` drawn from `config.options`. A bad `defaultValue` is a 400.
-- **A `button` prop is one unit.** Its value is `{ label, href, variant?, size?, arrow?, icon?,
-  newTab? }` and its `target.path` is `props` on a `button` block. For a new component never
-  declare a label prop plus a url prop: the two drift apart on the first edit.
-- **A button the site's own script handles has no href.** Its value is `{ label, action: "code",
-  variant?, size?, arrow?, icon? }`: a `<button type="button">` that opens a dialog, accepts
-  cookies or starts a tour. The label and the look are edited; the click stays the site's.
-  `href`, `newTab` and `rel` beside `action: "code"` are refused, and a value with neither an
-  href nor the action is refused as before. Setup derives these as button fields on a new
-  import. A control of the page itself is never one: a menu or theme toggle, a carousel arrow, a
-  dialog's close, an accordion or tab trigger, a copy button, a pagination step.
-- `target.blockId` + `target.path` must point at a real block and property inside the
-  component's own `blockJson`. Why: rendering copies each prop's value to that target; a target
-  that does not exist renders the default and the edit goes nowhere.
-- Every prop takes `helpText` and the component a `description` ("Hero with a heading,
-  supporting text and two buttons."). Leave them out: the platform writes the description, and
-  a prop's help only for a format or unit, a place the canvas cannot show, a real constraint or
-  a fallback (most props get none). Write your own by the rules in
-  [content-modeling.md](content-modeling.md) ("Writing help text"): one short plain sentence,
-  under 90 characters, with no semicolon, no dash and no figure taken from the page.
-- A prop takes `showIf` (`{ match, rules: [{ field, op, value? }] }`): hidden until SIBLING props match. `op` is `eq`, `neq`, `in`, `isSet`, `notEmpty` or `empty`; the last three take no `value`, the first three need one. Props and model fields share all six, and a sub-field's `showIf` names its sibling sub-fields.
-- `object` holds ONE `{ childKey: value }` built from `config.fields` (required), like the model field `object`. Groups, tables and objects nest to 10 levels counting the prop; an 11th is refused `field_depth_exceeded`. Aim an `object` at `props` or at a key your component code reads, never at a text slot such as a heading's `props.text` (`prop_target_unrenderable`).
-- `datetime`, `slug`, `email`, `phone`, `json`, `location` (`{ lat, lng }`), `tags` (`string[]`), `rating` (0..`config.max`) and `code` (`{ language?, code }` or a string) hold what the same-named model field holds, and a placement's value is checked by that field's rules (`prop_value_invalid`). Like `object`, a `tags` or `code` prop never targets a text slot.
-- `reference` holds one CMS item's id and `multi-reference` a list of them, as the model fields do: `config.contentModelId`, or `polymorphic: true` with `allowedModelSlugs` (one of the two is required), and `min`/`max` on the list. A placement's new id must exist (`REF_MISSING`); an id already stored is never re-checked. Page reads (delivery, preview) hydrate the ids to entries at their `depth`, so component code reads the entry; on a heading or button text slot the entry's title renders. A `multi-reference` never targets a text slot.
-- `update_component` replaces the whole `props` array. Read with `get_component`, change, write
-  all props back.
-- `select` and `multiselect` need `config.options`; `slot` holds one nested component instance,
-  or a list of them with `config.multiple`; `form` holds one Form document.
-- `slot` and `form` are reference-shaped: `target.path` is `props` (the whole envelope) on an
-  empty `component` or `form` block, and their values are `{ componentId, overrides? }` and
-  `{ formId }`. Neither may appear inside a `group` or `table` row.
-- **A `slot` with `config.multiple: true` holds a list.** Its value is
-  `[{ componentId, overrides? }, ...]` and its `target.path` is a container's child list:
-  `props.children` on a `section` block, or `props.columns.<n>` on a `columns` block (never
-  `props` on a `component` block). Each item is drawn there as a child component, in order.
-  Until a placement sets the slot, the children the definition holds in that list are shown;
-  `[]` shows none.
-  - `config.maxItems` defaults to 12 and cannot pass 50. `config.minItems` and
-    `config.componentIds` (which components may be listed) are checked on every write.
-  - An item may also carry `style` (use it for `hideOn`) and `window` with `from` / `until`
-    as UTC to the second (`2026-11-27T00:00:00Z`). A `defaultValue` must be an array and takes
-    no `window`.
-  - A write is a 400 whose message starts with the code: `slot_too_many`, `slot_too_few`,
-    `slot_item_invalid`, `slot_component_not_allowed`, `slot_component_unknown` (not a
-    component of this project), `component_cycle` (a component would end up inside itself,
-    through any chain), `component_too_deep` (more than 10 levels), `slot_target_invalid`,
-    `slot_not_multiple` (a list sent to a single slot). A value that is already stored is not
-    refused when the page is saved again.
-  - A child's copy is not click-to-edit on the canvas. Change it in the placement's
-    `overrides.<slot key>` list with `update_page`.
-  - Publish every listed component: a draft child renders nothing, like any draft component.
-- **A `form` prop stores an id, nothing more.** Modelling the questions again as props gives you
-  two answers to "what does this form ask?", and they diverge at the first edit on either side.
-  The save schema is `.strict()`, so posting the hydrated form object back is a 400, not a silent
-  strip — you find out at the write, not at the render.
-- A draft form is a 403 at every public ingress, so it renders nothing on the live site. Publish
-  it before pointing a component at it.
-
-### Where a form prop actually renders
-
-The prop binds which form. What the READER does with it depends on how the component was built,
-and only the first row below changes the rendered fields:
-
-| Component | Preview / Output | The form comes from | Does the prop change the fields? |
-|---|---|---|---|
-| Built from blocks (a `form` block in `blockJson`) | no Output — Output needs a recorded source file | the renderer's forms map | **yes**, on the live site and the page preview |
-| A component that renders `<BcmsForm>` / `<BcmsBlocks forms>` | yes | a forms catalogue passed beside the blocks | yes, where the catalogue reaches it |
-| A codemod section (`@bettercms-ai/convert`) | yes | static markup; convert stamps `data-bcms-form` onto the existing `<form>` | no — the fields are hand-written HTML |
-| A page route that fetches `/forms/public/:id` itself | inert (page-kind Output never runs scripts) | its own fetch | no |
-
-## 2. Instances
-
-A placed component is a block `{ type: "component", props: { componentId, overrides?, bind?,
-source? } }`.
-
-- `overrides` is keyed by prop `key`. Rendering walks the definition's props and takes an
-  override only for a declared key. An override under any other key is ignored.
-- A richtext override is a Portable Text array ([portable-text.md](portable-text.md)).
-- Inside an instance, edit addresses are `<instanceId>__overrides.<key>`.
-
-## 3. Sections, families and variants
-
-- A page is made of sections. A band used on more than one page, or with layout variants, is a
-  component with a `sectionType`. A true one-off is a `section` block whose `props.children` hold
-  its blocks.
-- Components that share a `sectionType` are one family: its variants.
-- **A section has a kind and a title, and only the kind is a name.** `sectionType` is the KIND
-  (`Hero`, `Logo cloud`, `Pricing`, `FAQ`): what the picker lists and the outline prints under each
-  section. It is the one thing to work out and name. The component's `name` is the layout within
-  that kind (`Centered`). The TITLE is the section's own heading, as written, which the outline
-  reads live from the section's content: nobody writes it, and a block `label` is only a person's
-  rename. Why: one string doing all three made two heroes collide (`Hero`, `Hero 2`) and gave a
-  component reused on a second page the first page's headline for a name. Never put a heading in
-  `sectionType` or `name`, and never write a `label` that rewords a heading or repeats the kind.
-- **A built-in section is a starting point, not a thing you place.** `list_components` shows the
-  locked `builtin:*` blueprints; `create_component` with `from: "builtin:hero-centered"` copies
-  one into the project as an ordinary draft component, then edit and publish it like any other.
-  Whatever you send (`name`, `slug`, `props`, `blockJson`, `sectionType`, `category`) wins over
-  the copy. `list_components` `sourceKey` says which built-in a component came from. A copy
-  never follows later changes to the built-in. An unknown id is 404 `BUILTIN_NOT_FOUND`.
-- **Give every component a library `category` as well.** Why: `sectionType` groups a family, the
-  category is how the component library lists it — an uncategorised component is created fine and
-  is then hard to find in the picker, which is where a human looks for it.
-- **Spell `sectionType` exactly the same on every variant**, same case, no spaces. Why: the
-  backend (including the key-drift check) groups families case-insensitively but the dashboard
-  picker only trims, so "Hero" and "hero" are one family to the backend and two in the picker.
-- **Every variant in a family declares the same prop keys with the same types.** Why: a variant
-  swap changes only `componentId`; the overrides stay, and only keys the new variant declares
-  are rendered. A key the new variant lacks is dropped from view; a key with a different type
-  renders wrong.
-- Before swapping, compare `get_component` props of both variants. If keys differ, tell the user
-  which values will not show.
-- **A card's or badge's looks are a `variant` select prop, not a family.** A card that comes as
-  Default, Featured and Outline is ONE component with a `select` prop keyed `variant` whose options
-  are the looks, and its markup picks classes from that value. Why: an editor switches the look in
-  place and the content stays put, and the library holds one card, not three. Families of looks
-  (`variantOf`, a style select on every section that places them) are for buttons. On a site
-  built in BetterCMS a new button look is `get_component`, then `create_component` with
-  `variantOf` naming the base. On an imported site the family is read, not written (§5).
-- Read `warnings` and act on them; they never block the write:
-  - `create_component` / `update_component`: `VARIANT_PROP_KEYS_MISMATCH` (a key no sibling
-    declares, or one siblings declare that this variant lacks) and `VARIANT_PROP_TYPE_MISMATCH`
-    (same key, different type).
-  - `update_page` with `blockJson` that swaps a component block: `COMPONENT_SWAP_DROPS_OVERRIDES`
-    (overrides the new component does not render; they stay on the block, so swapping back
-    restores them) and `COMPONENT_SWAP_PROP_TYPE_CHANGED`.
-
-Pitfalls of a component library:
-
-| Pitfall | Signal | Fix |
-|---|---|---|
-| A variant needs keys its siblings lack | `VARIANT_PROP_KEYS_MISMATCH` on every write to it | It is a different band: give it its own `sectionType` family |
-| Near-identical components in separate families ("Hero", "Hero 2", "Home hero") | Several families whose `get_component` props match | One family, variants by layout; every extra family is one more choice in "Add a section" |
-| A component nobody can insert | its id in `get_site_composition` `notInPicker` | Set its `sectionType` |
-| Components nothing places | ids in `get_site_composition` `unused` | Place them or name them to the user; deleting a component is a dashboard action |
-| A required prop left empty | `emptyRequiredProps` on a placement | Fill it; `required` is not enforced on write |
-| Props labelled by their copy or a generic role ("Text") | `get_next_steps` lists `labels-are-copy` | Label and help-text each prop from the site's code (`update_component` `propLabel`, `propHelpText`) |
-| Repeated cards as one prop per card | `plan1Title`, `plan2Title`… | One list prop whose rows are the cards |
-
-## 4. Publishing
-
-Publish with `publish_component` or `publish_components` (batch). A refusal is a 409 with a code.
-Handle by code, never by retrying the same call:
-
-| Code | Meaning | What to do |
-|---|---|---|
-| `COMPONENT_BLUEPRINT_MATERIALIZATION_REQUIRED` | You tried to publish a platform built-in | Create a project-local component from it, publish that |
-| `COMPONENT_PROJECT_SCOPED_RELEASE_REQUIRED` | The component is workspace-global | Create a project-local variant, publish that |
-| `COMPONENT_IMPLEMENTATION_NOT_READY` | A REPO-managed component lacks exact evidence and human approval, or a variant-group member (the provisioned navigation and footer) has a family contract that is unpublished. Never a `create_component` component outside a variant group: that one is dashboard-managed and publishes on the preflight alone | Report `readiness`; the owner resolves it in the dashboard |
-| `COMPONENT_ORCHESTRATION_V2_REQUIRED` | The project runs implementation in Agent Dock | Continue there; stop here |
-| `COMPONENT_PUBLISH_CONFLICT` | The component or its evidence changed mid-publish | Re-read with `get_component`, then publish once more |
-| `COMPONENT_PROJECT_CONTEXT_MISMATCH` | The component's `projectId` differs from the request's project scope | Call with the component's own project |
-
-### Site chrome (navigation and footer)
-
-A new project's navigation and footer are draft components placed in a draft Global Layout.
-Nothing of the chrome is live until all three are published, in this order:
-
-1. `publish_component` for navigation-default and footer-default. Each can be published while the
-   other is still draft; the publish is refused only for problems it would itself create.
-2. `publish_layout` with the revision from `get_layout`.
-3. `get_layout` with copy "published" to confirm.
-
-The navigation's logo is optional. When it is empty, the nav shows the brand mark
-(`set_brand_assets`) or the site name. Never generate or add a logo the site does not have. A
-page that renders its own header or footer does not get the Layout's copy on top of it.
-
-## 5. Rendering components in your site
-
-- **Next**: `readComponents()` from `@bettercms-ai/next` reads definitions from the
-  `bcms-content.json` snapshot. Pass them to `<BcmsBlocks components={…}>`; each `component`
-  block is resolved by applying its overrides to the definition.
-- **Astro**: `BcmsBlocks.astro` takes the same `components` prop. Without it every instance
-  renders nothing. Get definitions from `readComponents()` of `@bettercms-ai/next` or the
-  delivery components endpoint.
-- **SDK only**: `listComponents()` on the read client.
-
-Rule: if an instance renders empty, check that definitions were passed before debugging the
-component.
-
-### When the site's own code renders the sections
-
-A code-built site ships only what its templates draw, whatever the page's `blockJson` says. The
-setup gate judges it per route (`sections` and `style`, [finish-site.md](finish-site.md)), and
-adding or spacing one section is the recipe in [publishing.md](publishing.md).
-
-- **Render the page's block list, never hard-coded bands.** A section added or moved in the
-  editor reaches the live site only when the template loops over the page's blocks in order and
-  each section root carries its block id as `data-bcms-block`. The codemod writes both: `--sections`
-  wraps a page as it is (below), and `--componentize` lifts its bands into components and
-  generates `src/lib/bcms-sections.ts` for the loop. Until one ships, the
-  editor still adds, moves, swaps and removes sections (saved, and drawn on the canvas at once),
-  tells the author that publishing leaves the live order to the site's code, and its "Let BetterCMS
-  control section order" button commits that same codemod to the connected repository. `submit_conversion_receipt` keeps
-  `complete: false` with one `SECTIONS_UNSTAMPED` row per route.
-- **A page of imported section components is wrapped, not lifted.** `<BcmsSections>` takes each
-  top-level section as a named slot and draws the block list in order, stamping each section's
-  own root; a section added in the editor renders between them. `bettercms init` writes and
-  commits the wrap; what it refused, and the markup to write by hand, is in
-  [componentize.md](componentize.md) §5.
-- **The order is measured, not assumed.** A release reads the stamped section roots in document order:
-  a build that draws them in the CMS order (`ordered: true` on the binding report's structure row)
-  owns nothing, whatever sections it has no code for; one that draws them in its own order
-  (`ordered: false`) — a template that hardcodes its bands and stamps each with a snapshot id — is
-  code-ordered as soon as the CMS order moves. Stamp ids only from the loop, never as literals.
-- **No chrome placements on a page.** A nav, footer or modal placement the site's layout draws
-  renders nowhere, and the editor locks its outline row and skips it when it moves the sections
-  around it. Remove it.
-- **Spread `sectionRootAttrs(block)` on each root you write by hand** (`@bettercms-ai/astro`,
-  `@bettercms-ai/next`): it adds `data-bcms-block`, `data-bcms-style` and the block's style. The
-  editor offers section spacing and style handles only when every stamped root carries
-  `data-bcms-style`. A site converted before it existed shows none and `get_next_steps` lists
-  `upgrade-section-roots`. The fix is the codemod's `--upgrade-sections` mode, latest version, at
-  the repo root (`--dry-run` first); give each root it reports as skipped (`OWN_STYLE`, `SPREAD`,
-  `BLOCK_ID_ONLY`, …) its block style by hand, confirm with `--verify-styles`, push and release.
-- **A `button` field renders with `BcmsButton`** (`path`, `value`): one `<a data-bcms-button>`
-  carrying `data-variant` and `data-size`, so every look control (style, size, arrow, icon, new
-  tab) applies on the canvas and on publish. A value with `action: "code"` renders
-  `<button type="button" data-bcms-button>` with the same children and no href: attach your
-  handler to it as before. A publish writes its label and look and never an href, a target or a
-  rel, and never turns it into an anchor.
-- **A button's looks are the ones the site already has.** Each release measures the built pages
-  and keeps the project's Button family equal to the looks found there. Style offers those looks
-  and no others, and a publish paints a pick with the site's own classes. Never write CSS for a
-  look so that a control "works": there is no fixed list of variants to implement. A `button`
-  value's `variant` is one of those looks; a refused value comes back with the looks the project
-  has. A look the site drops is flagged, never deleted. A new look is the owner's design
-  decision: add its class to the site, then Rebuild.
-- **Each look is named for the role it plays on that site, and a site has only the roles it
-  uses.** One site's family is Primary, Secondary, Tertiary; another's is Primary, Secondary,
-  Ghost, Outline, Text Link. Never create, rename toward, or ask for a role the site does not
-  use, and never number one ("Outline 2"): the release gives the names, in this order.
-
-  | Role | The look that gets it |
-  |---|---|
-  | The site's own name | A look the site names keeps that name: `btn-primary` is Primary, `btn-ghost` is Ghost, `data-variant="link"` is Text Link. Its stored `variant` value stays the site's own. |
-  | Primary | Exactly one: the filled look used most (placements, then pages, then hero placements). On a site that fills nothing, its most used outline or ghost. |
-  | Brand | The most used look filled with a colour, when Primary is a neutral dark or light fill, or when the site names a less used look Primary. |
-  | Secondary | The look most often beside Primary in a button group; else the next most used look that is not a text link. |
-  | Tertiary | A third filled look. Further fills are Dark, Light, or the colour's name. |
-  | Outline | Bordered and not filled. |
-  | Ghost | No fill and no border, padded like a button or filled on hover. |
-  | Text Link | A plain link the site styles as a call to action. Menu and footer links and links in copy are not looks. |
-
-  What counts as a button is one rule for the family and for the fields: what the site names one
-  (`btn`, `button`, `cta`, `role="button"`), or what its stylesheet paints as one (a fill or a
-  border of its own). Two looks paint nothing at rest and still count: a ghost, by its own padded
-  box, and a text link drawn as a row that underlines. In a menu those two count only beside a
-  painted button.
-
-  A light and a dark rendition, a hover or disabled state, a size, and one paint spelled in two
-  sets of classes are all ONE look. Two looks left with one role are told apart in words from
-  their paint ("Outline on dark", "Pill Outline"). A role once given stays: a look added later
-  takes a role that is free and renames nothing, and a name a person gave is never changed back.
-  Without the SDK, write that same anchor: `data-bcms-button="<path>"`, the label in its own
-  `<span data-bcms-field="<path>.label">`, the href through `data-bcms-props`. The arrow is the
-  `svg.bcms-btn-arrow` it draws; never leave a hand-written arrow `<svg>` beside it, or turning
-  the arrow off leaves one behind. A CTA whose look is hard-coded tells the editor "Style lives
-  in the site's code".
-- **Render a CTA as one button** (the fix a 409 `CODE_RENDERED_ROUTE` names: its `next` gives the
-  `route` and the pair's `keys`). On a route the site's app renders, the code reads the keys it
-  declares, so the swap is made in code, on a branch, never on the default one:
-  1. Find the anchor. Search the repo for the keys; follow them through props and bindings tables
-     to the component that writes the `<a>` (a page passes them to a layout component, which
-     passes them to the button component).
-  2. Render it with `BcmsButton` (`@bettercms-ai/astro/components/BcmsButton.astro`, or
-     `BcmsButton` from `@bettercms-ai/next`) under ONE key: the link key without `-href`. Pass
-     `value` as the entry's button when it holds one, else `{ label, href }` from the copy and
-     href the page renders today, so nothing changes until someone edits it. Keep the anchor's
-     classes on `class`.
-  3. Remove the old pair's stamps and reads for that anchor (`data-bcms-field`, `data-bcms-props`,
-     the lookups of the two old keys). Leave other callers of a shared component working.
-  4. Open a pull request. After it is merged and the site rebuilt, run `editor_setup`, then check
-     the page: the anchor carries `data-bcms-button="<key>"` and `get_binding_report` lists no
-     unmatched path for it. The button field is added by that build and starts from the pair's
-     label and link.
-- **Read a published value where the app renders the page** (the fix a publish that fails with
-  "Published, but this page's code doesn't read this field yet: `<key>`" names). On a route the
-  site's app renders, a stamp (`data-bcms-field`, a `bcmsBindings` entry) only says where a field
-  IS; the page shows a publish only when its code READS the value. In code, on a branch:
-  1. Read through the helper the conversion wrote (`bcms`, `bcmsRows`, `bcmsImage`, `bcmsLayout`
-     from `src/bcms-content.ts`) or the SDK's `readPublishedContent` / `publishedEntry`. Never read
-     a row of `bcms-content.json` by hand, and never bundle the file (`import`, `import.meta.glob`).
-  2. An image the page imports and passes on (`src={heroImage}` beside
-     `bcmsBindings={{ image: "<key>" }}`): pass `src={bcmsImage(<page snapshot>, "<key>", heroImage)}`.
-     The import stays the fallback; a published image is served from the copy BetterCMS places
-     beside the app. `npx @bettercms-ai/convert` makes this edit for every such call site.
-  3. Keep the hard-coded copy as the fallback argument, so a build with no content renders as today.
-  4. Open a pull request. After it is merged and the site rebuilt, publish the field again: the
-     toast reads "Live".
-
-## 6. Preview source
-
-- `set_component_source` records which file in the repo implements a component;
-  `clear_component_source` removes it. Previews and validation read this mapping.
-- **Call it as soon as you write the file, not at the end of the job.** Why: until the mapping
-  exists a preview refuses with `COMPONENT_SOURCE_NOT_RECORDED`, and that refusal arrives later,
-  in the dashboard, to whoever opened the component — not to you while you still have the path in
-  hand.
-- `@bettercms-ai/preview-runtime` builds component previews for Next and Astro apps and validates
-  components in CI. `@bettercms-ai/component-output` verifies preview sessions and runs the
-  preview bridge in your app.
-
-### Output validation
-
-A component's Output (its live preview) shows only after a validation run renders it. The run
-renders the component from its recorded file, or cuts it out of the deployed page by its
-`data-bcms-block` attribute. A component with neither has nothing to render, so its validation
-can only fail.
-
-Do these steps in order, every time you create or componentize a component:
-
-1. Make it renderable. Either call `set_component_source` with the file that renders it, or, after
-   `componentize_sections`, put each `blockId` from the receipt's `stamps` on its section root as
-   `data-bcms-block` (or run `npx @bettercms-ai/convert --componentize`, then
-   `submit_componentize_receipt`).
-2. Deploy, so the build that validation renders contains that markup.
-3. `get_component_readiness`. If `validation.gap` is set, do what `validation.fix` says first.
-4. `declare_component_route` only when the app serves previews somewhere other than the default route.
-5. `request_component_validation`. It refuses with 422 and the fix when nothing renders the
-   component, and opens no request.
-6. In the app's repository, run
-   `npx @bettercms-ai/preview-runtime validate --local --request <requestId>` with `BCMS_API_URL`,
-   `BCMS_API_KEY` (a project key with artifact write), `BCMS_PROJECT_ID` and `BCMS_PREVIEW_ORIGIN`
-   set in the environment. Never put a key in a tool call.
-7. `get_component_readiness` again. `outputReady` means the Output renders.
-
-Rules:
-
-- Your evidence is self-attested. Publishing still needs the owner's Visual Approval in the
-  dashboard. No tool gives it: never say you approved a component.
-- CI validation (GitHub Actions) runs in the owner's repository at the owner's cost. The tool
-  refuses it with "VALIDATION_PROVIDER_DASHBOARD_ONLY". Ask the owner to start it from the dashboard.
-- A validation failure naming "COMPONENT_SOURCE_NOT_RECORDED" means step 1 or 2 was skipped. It is
-  not a bug in the component.
-
-## 7. The values popover (dashboard)
-
-Where you edit decides what you change:
-
-- On a **placed instance** (a page body or rich-text field): the edit writes that instance's
-  override. Only this placement changes.
-- On the **component's own canvas**: the edit writes the default of the variant being edited
-  (Base, or the open variant). Every instance without an override changes.
-
-Rule: when the user says "change it on this page", edit the instance; "change it everywhere",
-edit the default. Say which one you did.
-
-## 8. Groups
-
-Components are organised into `component_groups` (the folders of the Components tab). A component
-`componentize_sections` creates belongs to ONE page, so it is filed by that page, not by family.
-
-- `componentize_sections` files every component it creates: under `group` when you pass one
-  (found or created by name); otherwise an MCP or release run files it under its page's folder,
-  `Sections/<Page title>` (`Sections/<Page title>/<pattern>` for a template), and a dashboard or
-  studio run leaves it unfiled. The receipt's `components.groups` lists the Groups it filed into.
-  A reused component keeps its Group.
-- Sections `editor_setup` componentizes are filed the same way.
-- `componentize_sections` reuses a component by identity and slug, never by family, so a
-  hand-built `Hero / Split` is not picked for a derived hero band. Run `dryRun: true` and read
-  `components.wouldDuplicate`: each id is an existing same-family component the run would sit a
-  new one beside. Decide with the user before applying.
-- Components componentized from the dashboard are not filed automatically.
-- File one yourself with `create_component` or `update_component` `group` (by name).
-
-Which pages use a component is computed on request by searching page and entry JSON; it is not a
-stored list.
-
-## 9. Verify
-
-1. `get_component` on each component you changed: props complete, `sectionType` spelled like its
-   siblings.
-2. `get_site_composition`: every page is sections; every component you meant to publish is
-   published.
-   - Per page: `kind` is `blocks`, `fields-only` or `empty`. `nonComponentBlocks` are loose
-     top-level bands the editor's section lane cannot outline.
-   - Per placement: the component's `status` is `published`, `draft` or `missing`. `inPicker` is
-     false for a component with no `sectionType`: "Add a section" does not offer it.
-     `emptyRequiredProps` is reported only here.
-   - Site-wide: `components` counts published and draft, `awaitingEvidence` and
-     `awaitingApproval`. A person approves in the dashboard, one component at a time. Then the
-     `notInPicker` and `unused` ids, and `layout.placements`: the chrome placed in the Global
-     Layout draft.
-3. `get_binding_report` on a page that uses the component: instance values bind.
+---
+title: "Components, props and variants"
+description: "The prop contract, instances, sectionType families and variants, publishing codes, rendering components in a site, preview source and component groups."
+---
+
+# Components, props and section variants
+
+Doctrine (components vs collections, section anatomy, variants): §3 and §4 of
+`bettercms://playbook/schema`; flows: `new_component` prompt, `componentize_site` prompt. This
+reference is what the code does with what you write. Componentizing a derived site end to end:
+[componentize.md](componentize.md).
+
+## Contents
+
+- [1. The prop contract](#1-the-prop-contract) · [2. Instances](#2-instances) ·
+  [3. Sections, families and variants](#3-sections-families-and-variants) ·
+  [4. Publishing](#4-publishing) · [5. Rendering components in your site](#5-rendering-components-in-your-site)
+- [6. Preview source](#6-preview-source) · [7. The values popover](#7-the-values-popover-dashboard) ·
+  [8. Groups](#8-groups) · [9. Verify](#9-verify)
+
+## 1. The prop contract
+
+A component declares `props`. Each prop is `{ key, label, type, target: { blockId, path },
+defaultValue? }`.
+
+- `type` is one of exactly 30: `text`, `richtext`, `image`, `url`, `boolean`, `number`, `select`, `group`, `table`, `slot`,
+  `form`, then `date`, `color`, `file`, `link`, `icon`, `multiselect` and `button`, then `object`, `datetime`, `slug`,
+  `email`, `phone`, `json`, `location`, `tags`, `rating`, `code`, `reference` and `multi-reference`.
+- The last seven store what the same-named model field stores: `date` is `YYYY-MM-DD`, `color` a
+  hex, `file` `{ url, name?, size? }`, `link` an href string or `{ href, rel?, newTab? }`, `icon` an icon name or an image
+  value, `multiselect` a `string[]` drawn from `config.options`. A bad `defaultValue` is a 400.
+- **A `button` prop is one unit.** Its value is `{ label, href, variant?, size?, arrow?, icon?,
+  newTab? }` and its `target.path` is `props` on a `button` block. For a new component never
+  declare a label prop plus a url prop: the two drift apart on the first edit.
+- **A button the site's own script handles has no href.** Its value is `{ label, action: "code",
+  variant?, size?, arrow?, icon? }`: a `<button type="button">` that opens a dialog, accepts
+  cookies or starts a tour. The label and the look are edited; the click stays the site's.
+  `href`, `newTab` and `rel` beside `action: "code"` are refused, and a value with neither an
+  href nor the action is refused as before. Setup derives these as button fields on a new
+  import. A control of the page itself is never one: a menu or theme toggle, a carousel arrow, a
+  dialog's close, an accordion or tab trigger, a copy button, a pagination step.
+- `target.blockId` + `target.path` must point at a real block and property inside the
+  component's own `blockJson`. Why: rendering copies each prop's value to that target; a target
+  that does not exist renders the default and the edit goes nowhere.
+- Every prop takes `helpText` and the component a `description` ("Hero with a heading,
+  supporting text and two buttons."). Leave them out: the platform writes the description, and
+  a prop's help only for a format or unit, a place the canvas cannot show, a real constraint or
+  a fallback (most props get none). Write your own by the rules in
+  [content-modeling.md](content-modeling.md) ("Writing help text"): one short plain sentence,
+  under 90 characters, with no semicolon, no dash and no figure taken from the page.
+- A prop takes `showIf` (`{ match, rules: [{ field, op, value? }] }`): hidden until SIBLING props match. `op` is `eq`, `neq`, `in`, `isSet`, `notEmpty` or `empty`; the last three take no `value`, the first three need one. Props and model fields share all six, and a sub-field's `showIf` names its sibling sub-fields.
+- `object` holds ONE `{ childKey: value }` built from `config.fields` (required), like the model field `object`. Groups, tables and objects nest to 10 levels counting the prop; an 11th is refused `field_depth_exceeded`. Aim an `object` at `props` or at a key your component code reads, never at a text slot such as a heading's `props.text` (`prop_target_unrenderable`).
+- `datetime`, `slug`, `email`, `phone`, `json`, `location` (`{ lat, lng }`), `tags` (`string[]`), `rating` (0..`config.max`) and `code` (`{ language?, code }` or a string) hold what the same-named model field holds, and a placement's value is checked by that field's rules (`prop_value_invalid`). Like `object`, a `tags` or `code` prop never targets a text slot.
+- `reference` holds one CMS item's id and `multi-reference` a list of them, as the model fields do: `config.contentModelId`, or `polymorphic: true` with `allowedModelSlugs` (one of the two is required), and `min`/`max` on the list. A placement's new id must exist (`REF_MISSING`); an id already stored is never re-checked. Page reads (delivery, preview) hydrate the ids to entries at their `depth`, so component code reads the entry; on a heading or button text slot the entry's title renders. A `multi-reference` never targets a text slot.
+- `update_component` replaces the whole `props` array. Read with `get_component`, change, write
+  all props back.
+- `select` and `multiselect` need `config.options`; `slot` holds one nested component instance,
+  or a list of them with `config.multiple`; `form` holds one Form document.
+- `slot` and `form` are reference-shaped: `target.path` is `props` (the whole envelope) on an
+  empty `component` or `form` block, and their values are `{ componentId, overrides? }` and
+  `{ formId }`. Neither may appear inside a `group` or `table` row.
+- **A `slot` with `config.multiple: true` holds a list.** Its value is
+  `[{ componentId, overrides? }, ...]` and its `target.path` is a container's child list:
+  `props.children` on a `section` block, or `props.columns.<n>` on a `columns` block (never
+  `props` on a `component` block). Each item is drawn there as a child component, in order.
+  Until a placement sets the slot, the children the definition holds in that list are shown;
+  `[]` shows none.
+  - `config.maxItems` defaults to 12 and cannot pass 50. `config.minItems` and
+    `config.componentIds` (which components may be listed) are checked on every write.
+  - An item may also carry `style` (use it for `hideOn`) and `window` with `from` / `until`
+    as UTC to the second (`2026-11-27T00:00:00Z`). A `defaultValue` must be an array and takes
+    no `window`.
+  - A write is a 400 whose message starts with the code: `slot_too_many`, `slot_too_few`,
+    `slot_item_invalid`, `slot_component_not_allowed`, `slot_component_unknown` (not a
+    component of this project), `component_cycle` (a component would end up inside itself,
+    through any chain), `component_too_deep` (more than 10 levels), `slot_target_invalid`,
+    `slot_not_multiple` (a list sent to a single slot). A value that is already stored is not
+    refused when the page is saved again.
+  - A child's copy is not click-to-edit on the canvas. Change it in the placement's
+    `overrides.<slot key>` list with `update_page`.
+  - Publish every listed component: a draft child renders nothing, like any draft component.
+- **A `form` prop stores an id, nothing more.** Modelling the questions again as props gives you
+  two answers to "what does this form ask?", and they diverge at the first edit on either side.
+  The save schema is `.strict()`, so posting the hydrated form object back is a 400, not a silent
+  strip — you find out at the write, not at the render.
+- A draft form is a 403 at every public ingress, so it renders nothing on the live site. Publish
+  it before pointing a component at it.
+
+### Where a form prop actually renders
+
+The prop binds which form. What the READER does with it depends on how the component was built,
+and only the first row below changes the rendered fields:
+
+| Component | Preview / Output | The form comes from | Does the prop change the fields? |
+|---|---|---|---|
+| Built from blocks (a `form` block in `blockJson`) | no Output — Output needs a recorded source file | the renderer's forms map | **yes**, on the live site and the page preview |
+| A component that renders `<BcmsForm>` / `<BcmsBlocks forms>` | yes | a forms catalogue passed beside the blocks | yes, where the catalogue reaches it |
+| A codemod section (`@bettercms-ai/convert`) | yes | static markup; convert stamps `data-bcms-form` onto the existing `<form>` | no — the fields are hand-written HTML |
+| A page route that fetches `/forms/public/:id` itself | inert (page-kind Output never runs scripts) | its own fetch | no |
+
+## 2. Instances
+
+A placed component is a block `{ type: "component", props: { componentId, overrides?, bind?,
+source? } }`.
+
+- `overrides` is keyed by prop `key`. Rendering walks the definition's props and takes an
+  override only for a declared key. An override under any other key is ignored.
+- A richtext override is a Portable Text array ([portable-text.md](portable-text.md)).
+- Inside an instance, edit addresses are `<instanceId>__overrides.<key>`.
+
+## 3. Sections, families and variants
+
+- A page is made of sections. A band used on more than one page, or with layout variants, is a
+  component with a `sectionType`. A true one-off is a `section` block whose `props.children` hold
+  its blocks.
+- Components that share a `sectionType` are one family: its variants.
+- **A section has a kind and a title, and only the kind is a name.** `sectionType` is the KIND
+  (`Hero`, `Logo cloud`, `Pricing`, `FAQ`): what the picker lists and the outline prints under each
+  section. It is the one thing to work out and name. The component's `name` is the layout within
+  that kind (`Centered`). The TITLE is the section's own heading, as written, which the outline
+  reads live from the section's content: nobody writes it, and a block `label` is only a person's
+  rename. Why: one string doing all three made two heroes collide (`Hero`, `Hero 2`) and gave a
+  component reused on a second page the first page's headline for a name. Never put a heading in
+  `sectionType` or `name`, and never write a `label` that rewords a heading or repeats the kind.
+- **A built-in section is a starting point, not a thing you place.** `list_components` shows the
+  locked `builtin:*` blueprints; `create_component` with `from: "builtin:hero-centered"` copies
+  one into the project as an ordinary draft component, then edit and publish it like any other.
+  Whatever you send (`name`, `slug`, `props`, `blockJson`, `sectionType`, `category`) wins over
+  the copy. `list_components` `sourceKey` says which built-in a component came from. A copy
+  never follows later changes to the built-in. An unknown id is 404 `BUILTIN_NOT_FOUND`.
+- **Give every component a library `category` as well.** Why: `sectionType` groups a family, the
+  category is how the component library lists it — an uncategorised component is created fine and
+  is then hard to find in the picker, which is where a human looks for it.
+- **Spell `sectionType` exactly the same on every variant**, same case, no spaces. Why: the
+  backend (including the key-drift check) groups families case-insensitively but the dashboard
+  picker only trims, so "Hero" and "hero" are one family to the backend and two in the picker.
+- **Every variant in a family declares the same prop keys with the same types.** Why: a variant
+  swap changes only `componentId`; the overrides stay, and only keys the new variant declares
+  are rendered. A key the new variant lacks is dropped from view; a key with a different type
+  renders wrong.
+- Before swapping, compare `get_component` props of both variants. If keys differ, tell the user
+  which values will not show.
+- **A card's or badge's looks are a `variant` select prop, not a family.** A card that comes as
+  Default, Featured and Outline is ONE component with a `select` prop keyed `variant` whose options
+  are the looks, and its markup picks classes from that value. Why: an editor switches the look in
+  place and the content stays put, and the library holds one card, not three. Families of looks
+  (`variantOf`, a style select on every section that places them) are for buttons. On a site
+  built in BetterCMS a new button look is `get_component`, then `create_component` with
+  `variantOf` naming the base. On an imported site the family is read, not written (§5).
+- Read `warnings` and act on them; they never block the write:
+  - `create_component` / `update_component`: `VARIANT_PROP_KEYS_MISMATCH` (a key no sibling
+    declares, or one siblings declare that this variant lacks) and `VARIANT_PROP_TYPE_MISMATCH`
+    (same key, different type).
+  - `update_page` with `blockJson` that swaps a component block: `COMPONENT_SWAP_DROPS_OVERRIDES`
+    (overrides the new component does not render; they stay on the block, so swapping back
+    restores them) and `COMPONENT_SWAP_PROP_TYPE_CHANGED`.
+
+Pitfalls of a component library:
+
+| Pitfall | Signal | Fix |
+|---|---|---|
+| A variant needs keys its siblings lack | `VARIANT_PROP_KEYS_MISMATCH` on every write to it | It is a different band: give it its own `sectionType` family |
+| Near-identical components in separate families ("Hero", "Hero 2", "Home hero") | Several families whose `get_component` props match | One family, variants by layout; every extra family is one more choice in "Add a section" |
+| A component nobody can insert | its id in `get_site_composition` `notInPicker` | Set its `sectionType` |
+| Components nothing places | ids in `get_site_composition` `unused` | Place them or name them to the user; deleting a component is a dashboard action |
+| A required prop left empty | `emptyRequiredProps` on a placement | Fill it; `required` is not enforced on write |
+| Props labelled by their copy or a generic role ("Text") | `get_next_steps` lists `labels-are-copy` | Label and help-text each prop from the site's code (`update_component` `propLabel`, `propHelpText`) |
+| Repeated cards as one prop per card | `plan1Title`, `plan2Title`… | One list prop whose rows are the cards |
+
+## 4. Publishing
+
+Publish with `publish_component` or `publish_components` (batch). A refusal is a 409 with a code.
+Handle by code, never by retrying the same call:
+
+| Code | Meaning | What to do |
+|---|---|---|
+| `COMPONENT_BLUEPRINT_MATERIALIZATION_REQUIRED` | You tried to publish a platform built-in | Create a project-local component from it, publish that |
+| `COMPONENT_PROJECT_SCOPED_RELEASE_REQUIRED` | The component is workspace-global | Create a project-local variant, publish that |
+| `COMPONENT_IMPLEMENTATION_NOT_READY` | A REPO-managed component lacks exact evidence and human approval, or a variant-group member (the provisioned navigation and footer) has a family contract that is unpublished. Never a `create_component` component outside a variant group: that one is dashboard-managed and publishes on the preflight alone | Report `readiness`; the owner resolves it in the dashboard |
+| `COMPONENT_ORCHESTRATION_V2_REQUIRED` | The project runs implementation in Agent Dock | Continue there; stop here |
+| `COMPONENT_PUBLISH_CONFLICT` | The component or its evidence changed mid-publish | Re-read with `get_component`, then publish once more |
+| `COMPONENT_PROJECT_CONTEXT_MISMATCH` | The component's `projectId` differs from the request's project scope | Call with the component's own project |
+
+### Site chrome (navigation and footer)
+
+A new project's navigation and footer are draft components placed in a draft Global Layout.
+Nothing of the chrome is live until all three are published, in this order:
+
+1. `publish_component` for navigation-default and footer-default. Each can be published while the
+   other is still draft; the publish is refused only for problems it would itself create.
+2. `publish_layout` with the revision from `get_layout`.
+3. `get_layout` with copy "published" to confirm.
+
+The navigation's logo is optional. When it is empty, the nav shows the brand mark
+(`set_brand_assets`) or the site name. Never generate or add a logo the site does not have. A
+page that renders its own header or footer does not get the Layout's copy on top of it.
+
+## 5. Rendering components in your site
+
+- **Next**: `readComponents()` from `@bettercms-ai/next` reads definitions from the
+  `bcms-content.json` snapshot. Pass them to `<BcmsBlocks components={…}>`; each `component`
+  block is resolved by applying its overrides to the definition.
+- **Astro**: `BcmsBlocks.astro` takes the same `components` prop. Without it every instance
+  renders nothing. Get definitions from `readComponents()` of `@bettercms-ai/next` or the
+  delivery components endpoint.
+- **SDK only**: `listComponents()` on the read client.
+
+Rule: if an instance renders empty, check that definitions were passed before debugging the
+component.
+
+### When the site's own code renders the sections
+
+A code-built site ships only what its templates draw, whatever the page's `blockJson` says. The
+setup gate judges it per route (`sections` and `style`, [finish-site.md](finish-site.md)), and
+adding or spacing one section is the recipe in [publishing.md](publishing.md).
+
+- **Render the page's block list, never hard-coded bands.** A section added or moved in the
+  editor reaches the live site only when the template loops over the page's blocks in order and
+  each section root carries its block id as `data-bcms-block`. The codemod writes both: `--sections`
+  wraps a page as it is (below), and `--componentize` lifts its bands into components and
+  generates `src/lib/bcms-sections.ts` for the loop. Until one ships, the
+  editor still adds, moves, swaps and removes sections (saved, and drawn on the canvas at once),
+  tells the author that publishing leaves the live order to the site's code, and its "Let BetterCMS
+  control section order" button commits that same codemod to the connected repository. `submit_conversion_receipt` keeps
+  `complete: false` with one `SECTIONS_UNSTAMPED` row per route.
+- **A page of imported section components is wrapped, not lifted.** `<BcmsSections>` takes each
+  top-level section as a named slot and draws the block list in order, stamping each section's
+  own root; a section added in the editor renders between them. `bettercms init` writes and
+  commits the wrap; what it refused, and the markup to write by hand, is in
+  [componentize.md](componentize.md) §5.
+- **The order is measured, not assumed.** A release reads the stamped section roots in document order:
+  a build that draws them in the CMS order (`ordered: true` on the binding report's structure row)
+  owns nothing, whatever sections it has no code for; one that draws them in its own order
+  (`ordered: false`) — a template that hardcodes its bands and stamps each with a snapshot id — is
+  code-ordered as soon as the CMS order moves. Stamp ids only from the loop, never as literals.
+- **No chrome placements on a page.** A nav, footer or modal placement the site's layout draws
+  renders nowhere, and the editor locks its outline row and skips it when it moves the sections
+  around it. Remove it.
+- **Spread `sectionRootAttrs(block)` on each root you write by hand** (`@bettercms-ai/astro`,
+  `@bettercms-ai/next`): it adds `data-bcms-block`, `data-bcms-style` and the block's style. The
+  editor offers section spacing and style handles only when every stamped root carries
+  `data-bcms-style`. A site converted before it existed shows none and `get_next_steps` lists
+  `upgrade-section-roots`. The fix is the codemod's `--upgrade-sections` mode, latest version, at
+  the repo root (`--dry-run` first); give each root it reports as skipped (`OWN_STYLE`, `SPREAD`,
+  `BLOCK_ID_ONLY`, …) its block style by hand, confirm with `--verify-styles`, push and release.
+- **A `button` field renders with `BcmsButton`** (`path`, `value`): one `<a data-bcms-button>`
+  carrying `data-variant` and `data-size`, so every look control (style, size, arrow, icon, new
+  tab) applies on the canvas and on publish. A value with `action: "code"` renders
+  `<button type="button" data-bcms-button>` with the same children and no href: attach your
+  handler to it as before. A publish writes its label and look and never an href, a target or a
+  rel, and never turns it into an anchor.
+- **A button's looks are the ones the site already has.** Each release measures the built pages
+  and keeps the project's Button family equal to the looks found there. Style offers those looks
+  and no others, and a publish paints a pick with the site's own classes. Never write CSS for a
+  look so that a control "works": there is no fixed list of variants to implement. A `button`
+  value's `variant` is one of those looks; a refused value comes back with the looks the project
+  has. A look the site drops is flagged, never deleted. A new look is the owner's design
+  decision: add its class to the site, then Rebuild.
+- **Each look is named for the role it plays on that site, and a site has only the roles it
+  uses.** One site's family is Primary, Secondary, Tertiary; another's is Primary, Secondary,
+  Ghost, Outline, Text Link. Never create, rename toward, or ask for a role the site does not
+  use, and never number one ("Outline 2"): the release gives the names, in this order.
+
+  | Role | The look that gets it |
+  |---|---|
+  | The site's own name | A look the site names keeps that name: `btn-primary` is Primary, `btn-ghost` is Ghost, `data-variant="link"` is Text Link. Its stored `variant` value stays the site's own. |
+  | Primary | Exactly one: the filled look used most (placements, then pages, then hero placements). On a site that fills nothing, its most used outline or ghost. |
+  | Brand | The most used look filled with a colour, when Primary is a neutral dark or light fill, or when the site names a less used look Primary. |
+  | Secondary | The look most often beside Primary in a button group; else the next most used look that is not a text link. |
+  | Tertiary | A third filled look. Further fills are Dark, Light, or the colour's name. |
+  | Outline | Bordered and not filled. |
+  | Ghost | No fill and no border, padded like a button or filled on hover. |
+  | Text Link | A plain link the site styles as a call to action. Menu and footer links and links in copy are not looks. |
+
+  What counts as a button is one rule for the family and for the fields: what the site names one
+  (`btn`, `button`, `cta`, `role="button"`), or what its stylesheet paints as one (a fill or a
+  border of its own). Two looks paint nothing at rest and still count: a ghost, by its own padded
+  box, and a text link drawn as a row that underlines. In a menu those two count only beside a
+  painted button.
+
+  A light and a dark rendition, a hover or disabled state, a size, and one paint spelled in two
+  sets of classes are all ONE look. Two looks left with one role are told apart in words from
+  their paint ("Outline on dark", "Pill Outline"). A role once given stays: a look added later
+  takes a role that is free and renames nothing, and a name a person gave is never changed back.
+  Without the SDK, write that same anchor: `data-bcms-button="<path>"`, the label in its own
+  `<span data-bcms-field="<path>.label">`, the href through `data-bcms-props`. The arrow is the
+  `svg.bcms-btn-arrow` it draws; never leave a hand-written arrow `<svg>` beside it, or turning
+  the arrow off leaves one behind. A CTA whose look is hard-coded tells the editor "Style lives
+  in the site's code".
+- **Render a CTA as one button** (the fix a 409 `CODE_RENDERED_ROUTE` names: its `next` gives the
+  `route` and the pair's `keys`). On a route the site's app renders, the code reads the keys it
+  declares, so the swap is made in code, on a branch, never on the default one:
+  1. Find the anchor. Search the repo for the keys; follow them through props and bindings tables
+     to the component that writes the `<a>` (a page passes them to a layout component, which
+     passes them to the button component).
+  2. Render it with `BcmsButton` (`@bettercms-ai/astro/components/BcmsButton.astro`, or
+     `BcmsButton` from `@bettercms-ai/next`) under ONE key: the link key without `-href`. Pass
+     `value` as the entry's button when it holds one, else `{ label, href }` from the copy and
+     href the page renders today, so nothing changes until someone edits it. Keep the anchor's
+     classes on `class`.
+  3. Remove the old pair's stamps and reads for that anchor (`data-bcms-field`, `data-bcms-props`,
+     the lookups of the two old keys). Leave other callers of a shared component working.
+  4. Open a pull request. After it is merged and the site rebuilt, run `editor_setup`, then check
+     the page: the anchor carries `data-bcms-button="<key>"` and `get_binding_report` lists no
+     unmatched path for it. The button field is added by that build and starts from the pair's
+     label and link.
+- **Read a published value where the app renders the page** (the fix a publish that fails with
+  "Published, but this page's code doesn't read this field yet: `<key>`" names). On a route the
+  site's app renders, a stamp (`data-bcms-field`, a `bcmsBindings` entry) only says where a field
+  IS; the page shows a publish only when its code READS the value. In code, on a branch:
+  1. Read through the helper the conversion wrote (`bcms`, `bcmsRows`, `bcmsImage`, `bcmsLayout`
+     from `src/bcms-content.ts`) or the SDK's `readPublishedContent` / `publishedEntry`. Never read
+     a row of `bcms-content.json` by hand, and never bundle the file (`import`, `import.meta.glob`).
+  2. An image the page imports and passes on (`src={heroImage}` beside
+     `bcmsBindings={{ image: "<key>" }}`): pass `src={bcmsImage(<page snapshot>, "<key>", heroImage)}`.
+     The import stays the fallback; a published image is served from the copy BetterCMS places
+     beside the app. `npx @bettercms-ai/convert` makes this edit for every such call site.
+  3. Keep the hard-coded copy as the fallback argument, so a build with no content renders as today.
+  4. Open a pull request. After it is merged and the site rebuilt, publish the field again: the
+     toast reads "Live".
+
+## 6. Preview source
+
+- `set_component_source` records which file in the repo implements a component;
+  `clear_component_source` removes it. Previews and validation read this mapping.
+- **Call it as soon as you write the file, not at the end of the job.** Why: until the mapping
+  exists a preview refuses with `COMPONENT_SOURCE_NOT_RECORDED`, and that refusal arrives later,
+  in the dashboard, to whoever opened the component — not to you while you still have the path in
+  hand.
+- `@bettercms-ai/preview-runtime` builds component previews for Next and Astro apps and validates
+  components in CI. `@bettercms-ai/component-output` verifies preview sessions and runs the
+  preview bridge in your app.
+
+### Output validation
+
+A component's Output (its live preview) shows only after a validation run renders it. The run
+renders the component from its recorded file, or cuts it out of the deployed page by its
+`data-bcms-block` attribute. A component with neither has nothing to render, so its validation
+can only fail.
+
+Do these steps in order, every time you create or componentize a component:
+
+1. Make it renderable. Either call `set_component_source` with the file that renders it, or, after
+   `componentize_sections`, put each `blockId` from the receipt's `stamps` on its section root as
+   `data-bcms-block` (or run `npx @bettercms-ai/convert --componentize`, then
+   `submit_componentize_receipt`).
+2. Deploy, so the build that validation renders contains that markup.
+3. `get_component_readiness`. If `validation.gap` is set, do what `validation.fix` says first.
+4. `declare_component_route` only when the app serves previews somewhere other than the default route.
+5. `request_component_validation`. It refuses with 422 and the fix when nothing renders the
+   component, and opens no request.
+6. In the app's repository, run
+   `npx @bettercms-ai/preview-runtime validate --local --request <requestId>` with `BCMS_API_URL`,
+   `BCMS_API_KEY` (a project key with artifact write), `BCMS_PROJECT_ID` and `BCMS_PREVIEW_ORIGIN`
+   set in the environment. Never put a key in a tool call.
+7. `get_component_readiness` again. `outputReady` means the Output renders.
+
+Rules:
+
+- Your evidence is self-attested. Publishing still needs the owner's Visual Approval in the
+  dashboard. No tool gives it: never say you approved a component.
+- CI validation (GitHub Actions) runs in the owner's repository at the owner's cost. The tool
+  refuses it with "VALIDATION_PROVIDER_DASHBOARD_ONLY". Ask the owner to start it from the dashboard.
+- A validation failure naming "COMPONENT_SOURCE_NOT_RECORDED" means step 1 or 2 was skipped. It is
+  not a bug in the component.
+
+## 7. The values popover (dashboard)
+
+Where you edit decides what you change:
+
+- On a **placed instance** (a page body or rich-text field): the edit writes that instance's
+  override. Only this placement changes.
+- On the **component's own canvas**: the edit writes the default of the variant being edited
+  (Base, or the open variant). Every instance without an override changes.
+
+Rule: when the user says "change it on this page", edit the instance; "change it everywhere",
+edit the default. Say which one you did.
+
+## 8. Groups
+
+Components are organised into `component_groups` (the folders of the Components tab). A component
+`componentize_sections` creates belongs to ONE page, so it is filed by that page, not by family.
+
+- `componentize_sections` files every component it creates: under `group` when you pass one
+  (found or created by name); otherwise an MCP or release run files it under its page's folder,
+  `Sections/<Page title>` (`Sections/<Page title>/<pattern>` for a template), and a dashboard or
+  studio run leaves it unfiled. The receipt's `components.groups` lists the Groups it filed into.
+  A reused component keeps its Group.
+- Sections `editor_setup` componentizes are filed the same way.
+- `componentize_sections` reuses a component by identity and slug, never by family, so a
+  hand-built `Hero / Split` is not picked for a derived hero band. Run `dryRun: true` and read
+  `components.wouldDuplicate`: each id is an existing same-family component the run would sit a
+  new one beside. Decide with the user before applying.
+- Components componentized from the dashboard are not filed automatically.
+- File one yourself with `create_component` or `update_component` `group` (by name).
+
+Which pages use a component is computed on request by searching page and entry JSON; it is not a
+stored list.
+
+## 9. Verify
+
+1. `get_component` on each component you changed: props complete, `sectionType` spelled like its
+   siblings.
+2. `get_site_composition`: every page is sections; every component you meant to publish is
+   published.
+   - Per page: `kind` is `blocks`, `fields-only` or `empty`. `nonComponentBlocks` are loose
+     top-level bands the editor's section lane cannot outline.
+   - Per placement: the component's `status` is `published`, `draft` or `missing`. `inPicker` is
+     false for a component with no `sectionType`: "Add a section" does not offer it.
+     `emptyRequiredProps` is reported only here.
+   - Site-wide: `components` counts published and draft, `awaitingEvidence` and
+     `awaitingApproval`. A person approves in the dashboard, one component at a time. Then the
+     `notInPicker` and `unused` ids, and `layout.placements`: the chrome placed in the Global
+     Layout draft.
+3. `get_binding_report` on a page that uses the component: instance values bind.