@bettercms-ai/mcp 0.83.0 → 0.83.2

package/dist/skills/bettercms/references/worked-examples.md

@@ -1,885 +1,885 @@
----
-title: "Worked examples"
-description: "Six conversions from source HTML to a production schema, a production value and a bound template: hero, feature grid, pricing with a comparison table, testimonials as a collection, FAQ with FAQPage markup, bento grid with per-cell sizes."
----
-
-# Worked examples: source HTML to schema, value and bound template
-
-Each example runs the same five steps: the source markup (trimmed), what it is and why, the
-schema as the write tool takes it, the value as the write tool takes it, and the template with
-its binding attributes. Copy the shape, never the customer's words. Rules behind the shapes:
-[content-modeling.md](content-modeling.md), [components.md](components.md),
-[bindings.md](bindings.md), [portable-text.md](portable-text.md). Examples 6 to 8 continue in
-[worked-examples-advanced.md](worked-examples-advanced.md).
-
-## Contents
-
-- [Which shape each example uses](#which-shape-each-example-uses)
-- [1. Hero with two buttons and a background image](#1-hero-with-two-buttons-and-a-background-image)
-- [2. Feature grid with icons](#2-feature-grid-with-icons)
-- [3. Pricing plans with a comparison table](#3-pricing-plans-with-a-comparison-table)
-- [4. Testimonials kept as a collection](#4-testimonials-kept-as-a-collection)
-- [5. FAQ accordion with FAQPage markup](#5-faq-accordion-with-faqpage-markup)
-- [9. Bento grid with per-cell sizes](#9-bento-grid-with-per-cell-sizes)
-- [Checks after any example](#checks-after-any-example)
-- Examples 6 to 8 (blog post as an entry, mega menu in the Global Layout, tabs holding columns
-  of cards): [worked-examples-advanced.md](worked-examples-advanced.md)
-
-## Which shape each example uses
-
-Production stores content in four places. Pick by what the markup is, then follow that example.
-
-| Markup | Stored as | Schema tool | Value tool | Address on the page | Example |
-|---|---|---|---|---|---|
-| A band one page owns | Page fields, keys prefixed by section | `create_page` `fields`, `add_field` | `set_page_content` | `data-bcms-field="<key>"` | 1, 2, 5 |
-| A band reused or with variants | Component with props | `create_component` | `compose_pages` (an instance per page) | `<instanceId>__overrides.<key>` | 3 |
-| Records that repeat on one route | Content model and entries | `create_content_model` | `create_content_entry` | the entry's field key | 4, 6 (advanced) |
-| Header, footer, promo bar | Global Layout Section | `update_layout` | `update_layout` | `data-bcms-layout-field` | 7 (advanced) |
-| A one-off band built from blocks | `section` block with child blocks | `update_page` `blockJson` | the same call | `<blockId>__<prop>` | 8 (advanced) |
-| Cells of different kinds, each with its own size | Component with a `slot` list and `slotSettings` | `create_component` | `compose_pages` | `<instanceId>__overrides.<key>` | 9 |
-
-Rules that hold in every example:
-
-- A key is unique in its whole model, so a page field carries its section: `"hero_title"`,
-  `"faq_title"`. Prop keys and sub-field keys live inside one component and stay short.
-- A field of type `text` is created as rich text. Send `richText: false` for every plain string
-  (a title, an eyebrow, a name, an icon name), then write it as a bare string.
-- A repeater value is `{ "repeatable": [ ...rows ] }`; a row is addressed `<key>[<n>].<childKey>`.
-- Bind the element that renders the value. Never a wrapper, never a list container.
-- `set_page_content` merges by top-level key. `compose_pages` and `update_page` `blockJson`
-  replace the page's whole block array: read `get_page` first and send every block back.
-
-## 1. Hero with two buttons and a background image
-
-Source: a freight-tracking home page.
-
-```html
-<section class="hero relative isolate overflow-hidden" id="top">
-  <picture class="absolute inset-0 -z-10">
-    <source type="image/avif" srcset="/img/hero-harbor-1280.avif 1280w, /img/hero-harbor-2560.avif 2560w">
-    <img src="/img/hero-harbor-1280.jpg" alt="Container cranes over a quiet harbor at dusk"
-      class="h-full w-full object-cover object-[50%_35%]" width="2560" height="1440">
-  </picture>
-  <div class="absolute inset-0 -z-10 bg-slate-950/50" aria-hidden="true"></div>
-  <div class="mx-auto max-w-6xl px-6 py-32 text-white">
-    <p class="text-sm uppercase text-teal-300">Freight visibility for mid-size shippers</p>
-    <h1 class="mt-4 text-5xl font-bold">Know where every container is before your customer asks.</h1>
-    <p class="mt-6 text-lg">Live ETAs from 140 carriers, delays flagged before they cost you, and one shared view for ops and sales.</p>
-    <a href="/demo" class="btn btn-primary">Book a demo <svg class="icon-arrow-right" aria-hidden="true"/></a>
-    <a href="https://app.kestrelfreight.com/signup" class="btn btn-ghost">Start free trial</a>
-    <p class="mt-8 text-sm"><span class="stars" role="img" aria-label="Rated 4.8 out of 5">★★★★★</span> 4.8 on G2 from 310 reviews</p>
-  </div>
-</section>
-```
-
-Reasoning:
-
-1. One `<h1>`, a lede, two links styled as buttons, a photo behind the copy: the page's opening
-   band. Other pages write their own hero copy, so this is page fields, not chrome.
-2. The uppercase line, the heading and the paragraph carry no links or emphasis: three plain
-   strings.
-3. Each `<a class="btn">` is one `button` field. Label, link and look travel together; the
-   trailing arrow is the button's `arrow`, not content.
-4. The `<picture>` is one `image` field. Store the largest source once and copy the `alt`. The CSS
-   `object-position: 50% 35%` is the focal point: divide by 100, so `{ x: 0.5, y: 0.35 }`.
-5. The stars are drawn from the number. Store `4.8` and the label; never the glyphs.
-6. The scrim, the padding and the teal colour are design. They stay in the site's classes.
-
-Schema (`create_page` `fields`, or one `add_field` with `pageId` per field):
-
-```json
-[
-  { "key": "hero_eyebrow", "label": "Eyebrow", "type": "text", "richText": false },
-  { "key": "hero_title", "label": "Heading", "type": "text", "richText": false, "required": true },
-  { "key": "hero_lede", "label": "Supporting text", "type": "text", "richText": false },
-  { "key": "hero_primary", "label": "Primary button", "type": "button" },
-  { "key": "hero_secondary", "label": "Secondary button", "type": "button" },
-  { "key": "hero_image", "label": "Background image", "type": "image",
-    "helpText": "Fills the whole band behind the text. Use a photo at least 2560 px wide." },
-  { "key": "hero_rating", "label": "Rating", "type": "number", "config": { "min": 0, "max": 5, "step": 0.1 },
-    "ui": { "control": "rating" } },
-  { "key": "hero_rating_label", "label": "Rating source", "type": "text", "richText": false }
-]
-```
-
-Value (`set_page_content`):
-
-```json
-{
-  "pageId": "<home page id>",
-  "data": {
-    "hero_eyebrow": "Freight visibility for mid-size shippers",
-    "hero_title": "Know where every container is before your customer asks.",
-    "hero_lede": "Live ETAs from 140 carriers, delays flagged before they cost you, and one shared view for ops and sales.",
-    "hero_primary": { "label": "Book a demo", "href": "/demo", "arrow": true },
-    "hero_secondary": { "label": "Start free trial", "href": "https://app.kestrelfreight.com/signup" },
-    "hero_image": {
-      "url": "/img/hero-harbor-2560.jpg",
-      "altText": "Container cranes over a quiet harbor at dusk",
-      "focal": { "x": 0.5, "y": 0.35 }
-    },
-    "hero_rating": 4.8,
-    "hero_rating_label": "on G2 from 310 reviews"
-  }
-}
-```
-
-Bound template (classes unchanged, shortened here):
-
-```html
-<section class="hero ..." id="top">
-  <picture class="absolute inset-0 -z-10">
-    <img src="/img/hero-harbor-1280.jpg" alt="Container cranes over a quiet harbor at dusk"
-      data-bcms-field="hero_image" data-bcms-kind="image">
-  </picture>
-  <div class="absolute inset-0 -z-10 bg-slate-950/50" aria-hidden="true"></div>
-  <p data-bcms-field="hero_eyebrow" data-bcms-kind="text">Freight visibility for mid-size shippers</p>
-  <h1 data-bcms-field="hero_title" data-bcms-kind="text">Know where every container is before your customer asks.</h1>
-  <p data-bcms-field="hero_lede" data-bcms-kind="text">Live ETAs from 140 carriers, ...</p>
-  <a class="btn btn-primary" href="/demo" data-bcms-button="hero_primary"
-    data-bcms-props="hero_primary.href|url|href">
-    <span data-bcms-field="hero_primary.label" data-bcms-kind="text">Book a demo</span></a>
-  <a class="btn btn-ghost" href="https://app.kestrelfreight.com/signup" data-bcms-button="hero_secondary"
-    data-bcms-props="hero_secondary.href|url|href">
-    <span data-bcms-field="hero_secondary.label" data-bcms-kind="text">Start free trial</span></a>
-  <p><span class="stars" role="img" aria-label="Rated 4.8 out of 5">★★★★★</span>
-    <span data-bcms-field="hero_rating">4.8</span>
-    <span data-bcms-field="hero_rating_label" data-bcms-kind="text">on G2 from 310 reviews</span></p>
-</section>
-```
-
-- The image binding sits on the `<img>`, not the `<picture>`. The alt text travels in the image
-  value (`altText`): a publish writes it to the bound element's `alt`. When `get_conversion_brief`
-  lists a separate alt path, declare that path in `data-bcms-props` with kind `text`.
-- Neither button value names a `variant`: the anchors keep the site's own `btn-primary` and
-  `btn-ghost`, and the release reads those two looks into the project's Button family.
-- An `href` is kind `url`, never `text`. The label gets its own `<span>` so a save does not erase
-  the arrow; the arrow is drawn by `BcmsButton` ([components.md](components.md)), so remove the
-  hand-written `<svg>` once the button renders through it.
-- A number shown as text binds with no kind. `number` is a kind only inside `data-bcms-props`.
-- The image value's `focal` frames this placement only; the asset's own focal point is untouched.
-
-Not available today: an overlay, height or theme token on the section. The scrim and spacing stay
-in the template's classes and change in code.
-
-## 2. Feature grid with icons
-
-Source: a finance SaaS product page.
-
-```html
-<section class="features py-24" aria-labelledby="features-title">
-  <span class="kicker">Why teams switch</span>
-  <h2 id="features-title">Everything your finance team asked for, in one close.</h2>
-  <p class="lede">Ledgerly connects to your bank, your payroll and your ERP, then does the matching for you.</p>
-  <ul class="grid gap-8 md:grid-cols-3" role="list">
-    <li class="feature-card">
-      <span class="icon-tile"><svg class="lucide lucide-zap" aria-hidden="true"><use href="#zap"/></svg></span>
-      <h3>Close in two days</h3>
-      <p>Auto-matching clears 92% of transactions before anyone opens a spreadsheet.</p>
-      <a class="text-link" href="/product/reconciliation">How matching works <span aria-hidden="true">→</span></a>
-    </li>
-    <li class="feature-card">
-      <span class="icon-tile"><svg class="lucide lucide-shield-check" aria-hidden="true"><use href="#shield-check"/></svg></span>
-      <h3>Audit-ready by default</h3>
-      <p>Every change is logged with who, when and why, so year-end takes hours.</p>
-    </li>
-    <!-- third card: plug, "40 native integrations", link to /integrations -->
-  </ul>
-  <a class="btn btn-outline mt-12" href="/product">Explore the product</a>
-</section>
-```
-
-Reasoning:
-
-1. A heading group, then same-shaped `<li>` cards: a repeater. The count and order are the
-   editor's; the three-column grid is the template's.
-2. Per card: the `<h3>` and the `<p>` are plain strings. The trailing link is optional, so the
-   second card leaves it empty. Never invent a link to fill the row.
-3. The icon is a sprite reference (`<use href="#zap"/>`), so the content is its name. Store the
-   name the site's own sprite uses (`zap`), as a plain string. An inline `<svg>` with its own
-   paths is different: that is an `image` field with `config: { "media": "icon" }`.
-4. The band's last button is a `button` field of its own, outside the repeater.
-
-Schema:
-
-```json
-[
-  { "key": "features_eyebrow", "label": "Eyebrow", "type": "text", "richText": false },
-  { "key": "features_title", "label": "Heading", "type": "text", "richText": false },
-  { "key": "features_intro", "label": "Intro", "type": "text", "richText": false },
-  { "key": "features_items", "label": "Features", "type": "repeater",
-    "ui": { "preview": { "title": "features_item_title" }, "itemLabel": "Feature" },
-    "fields": [
-      { "key": "features_item_icon", "label": "Icon", "type": "text", "richText": false,
-        "helpText": "Icon name from the site's sprite, lowercase with hyphens: zap, shield-check, plug." },
-      { "key": "features_item_title", "label": "Title", "type": "text", "richText": false },
-      { "key": "features_item_body", "label": "Description", "type": "text", "richText": false },
-      { "key": "features_item_link", "label": "Link", "type": "button" }
-    ] },
-  { "key": "features_cta", "label": "Button", "type": "button" }
-]
-```
-
-Value (`set_page_content` `data`):
-
-```json
-{
-  "features_eyebrow": "Why teams switch",
-  "features_title": "Everything your finance team asked for, in one close.",
-  "features_intro": "Ledgerly connects to your bank, your payroll and your ERP, then does the matching for you.",
-  "features_items": { "repeatable": [
-    { "features_item_icon": "zap", "features_item_title": "Close in two days",
-      "features_item_body": "Auto-matching clears 92% of transactions before anyone opens a spreadsheet.",
-      "features_item_link": { "label": "How matching works", "href": "/product/reconciliation", "variant": "link" } },
-    { "features_item_icon": "shield-check", "features_item_title": "Audit-ready by default",
-      "features_item_body": "Every change is logged with who, when and why, so year-end takes hours." },
-    { "features_item_icon": "plug", "features_item_title": "40 native integrations",
-      "features_item_body": "Banks, payroll and ERPs sync every hour without CSV exports.",
-      "features_item_link": { "label": "See integrations", "href": "/integrations", "variant": "link" } }
-  ] },
-  "features_cta": { "label": "Explore the product", "href": "/product", "variant": "outline" }
-}
-```
-
-Bound template (first card):
-
-```html
-<h2 id="features-title" data-bcms-field="features_title" data-bcms-kind="text">Everything your finance team asked for, in one close.</h2>
-<ul class="grid gap-8 md:grid-cols-3" role="list">
-  <li class="feature-card">
-    <span class="icon-tile"><svg class="lucide lucide-zap" aria-hidden="true"><use href="#zap"/></svg></span>
-    <h3 data-bcms-field="features_items[0].features_item_title" data-bcms-kind="text">Close in two days</h3>
-    <p data-bcms-field="features_items[0].features_item_body" data-bcms-kind="text">Auto-matching clears 92% ...</p>
-    <a class="text-link" href="/product/reconciliation" data-bcms-button="features_items[0].features_item_link"
-      data-bcms-props="features_items[0].features_item_link.href|url|href">
-      <span data-bcms-field="features_items[0].features_item_link.label" data-bcms-kind="text">How matching works</span>
-      <span aria-hidden="true">→</span></a>
-  </li>
-</ul>
-```
-
-- The `<ul>` carries no binding. Rows are added, removed and reordered in the side panel.
-- Emit an address only for a row that exists, and only for a link the row holds.
-- The icon `<svg>` is not bound: no field is read from text inside an SVG. The name is edited in
-  the side panel and the template turns it into the sprite reference.
-
-To make the icon editable, add a field of type `icon`: its value is a BetterCMS icon name or an
-uploaded icon, and a name off the set is refused. A component prop of type `icon` takes the same
-value ([components.md](components.md) §1). An inline SVG stays an `image` with `media: "icon"`.
-
-## 3. Pricing plans with a comparison table
-
-Source: a social scheduling SaaS. The same band sits on the pricing page and the home page, so
-it is a component.
-
-```html
-<section class="pricing" id="pricing">
-  <p class="eyebrow">Pricing</p>
-  <h2>Plans that grow with your calendar</h2>
-  <div class="billing-toggle" role="radiogroup" aria-label="Billing period">
-    <button role="radio" aria-checked="false" data-cycle="monthly">Monthly</button>
-    <button role="radio" aria-checked="true" data-cycle="yearly">Yearly <span class="pill">Save 20%</span></button>
-  </div>
-  <div class="plans grid md:grid-cols-3">
-    <article class="plan">
-      <h3>Starter</h3><p class="plan__for">For solo creators</p>
-      <p class="price"><span class="amount">$0</span></p>
-      <ul class="checks"><li>3 social accounts</li><li>30 scheduled posts a month</li></ul>
-      <a class="btn btn-outline" href="https://app.cadence.so/signup">Start free</a>
-    </article>
-    <article class="plan plan--featured">
-      <span class="ribbon">Most popular</span>
-      <h3>Growth</h3><p class="plan__for">For growing marketing teams</p>
-      <p class="price"><span class="amount" data-monthly="30" data-yearly="24">$24</span><span class="per">/mo</span></p>
-      <ul class="checks"><li>15 social accounts</li><li>Approval workflows</li><li>AI caption drafts</li></ul>
-      <a class="btn btn-primary" href="https://app.cadence.so/signup?plan=growth">Start 14-day trial</a>
-    </article>
-    <!-- Scale: "For agencies and brands", price "Let's talk", link /contact-sales -->
-  </div>
-  <table class="compare">
-    <thead><tr><th></th><th scope="col">Starter</th><th scope="col">Growth</th><th scope="col">Scale</th></tr></thead>
-    <tbody>
-      <tr class="group"><th colspan="4" scope="colgroup">Usage</th></tr>
-      <tr><th scope="row">Scheduled posts</th><td>30 a month</td><td>Unlimited</td><td>Unlimited</td></tr>
-      <tr class="group"><th colspan="4" scope="colgroup">Features</th></tr>
-      <tr><th scope="row">AI caption drafts</th><td><svg class="i-x" aria-label="Not included"/></td><td>50 a month</td><td><svg class="i-check" aria-label="Included"/></td></tr>
-    </tbody>
-  </table>
-  <p class="fineprint">Prices in USD, excluding tax. Yearly plans are billed once a year.</p>
-</section>
-```
-
-Reasoning:
-
-1. Plan cards and the comparison table share plan names and always show together: one section.
-2. Plans are same-shaped rows: one `table` prop. `data-monthly` and `data-yearly` give two
-   numbers; store numbers, never `$24/mo`. A price in words ("Let's talk") is its own text key,
-   shown when the numbers are empty.
-3. Each plan's check list is a list inside a row: a nested `table` whose rows hold one string.
-   That is the deepest a prop goes: the inner row takes scalars only.
-4. The comparison is a second `table` prop: one row object per feature, one text key per plan,
-   plus the group it sits under. The template prints a group row when `group` changes. Read
-   "Included" and "Not included" from `aria-label`, store "Yes" and "No", and let the template
-   draw the icon.
-5. A CTA inside a component is one `button` block that two props target (`text`, `url`).
-
-Schema (`create_component`; lands as a draft, then `publish_component`):
-
-```json
-{
-  "name": "Pricing / Three plans",
-  "slug": "pricing-three-plans",
-  "category": "conversion",
-  "sectionType": "Pricing",
-  "description": "Plan cards with monthly and yearly prices, then a feature comparison.",
-  "blockJson": [
-    { "type": "section", "id": "pr-root", "props": { "children": [
-      { "type": "text", "id": "pr-eyebrow", "props": { "html": "" } },
-      { "type": "heading", "id": "pr-heading", "props": { "text": "", "level": 2 } },
-      { "type": "text", "id": "pr-saving", "props": { "html": "" } },
-      { "type": "section", "id": "pr-plans", "label": "Plans", "props": { "children": [
-        { "type": "heading", "id": "pr-plan-name", "props": { "text": "", "level": 3 } },
-        { "type": "button", "id": "pr-plan-cta", "props": { "text": "", "href": "" } }
-      ] } },
-      { "type": "section", "id": "pr-compare", "label": "Comparison", "props": { "children": [
-        { "type": "heading", "id": "pr-compare-feature", "props": { "text": "", "level": 4 } }
-      ] } },
-      { "type": "text", "id": "pr-fineprint", "props": { "html": "" } }
-    ] } }
-  ],
-  "props": [
-    { "key": "eyebrow", "label": "Eyebrow", "type": "text", "target": { "blockId": "pr-eyebrow", "path": "props.html" } },
-    { "key": "heading", "label": "Heading", "type": "text", "target": { "blockId": "pr-heading", "path": "props.text" } },
-    { "key": "saving", "label": "Yearly saving badge", "type": "text", "target": { "blockId": "pr-saving", "path": "props.html" } },
-    { "key": "plans", "label": "Plans", "type": "table", "target": { "blockId": "pr-plans", "path": "props.rows" },
-      "ui": { "preview": { "title": "name" }, "itemLabel": "Plan" },
-      "config": { "fields": [
-        { "key": "name", "label": "Name", "type": "text" },
-        { "key": "audience", "label": "Who it is for", "type": "text" },
-        { "key": "badge", "label": "Badge", "type": "text" },
-        { "key": "monthly", "label": "Monthly price", "type": "number", "helpText": "Per month, billed monthly. Digits only." },
-        { "key": "yearly", "label": "Yearly price", "type": "number", "helpText": "Per month, when billed yearly. Digits only." },
-        { "key": "priceLabel", "label": "Price in words", "type": "text", "helpText": "Shown when both prices are empty." },
-        { "key": "features", "label": "Included", "type": "table", "fields": [
-          { "key": "line", "label": "Feature", "type": "text" }
-        ] },
-        { "key": "ctaLabel", "label": "Button label", "type": "text" },
-        { "key": "ctaUrl", "label": "Button link", "type": "url" }
-      ] } },
-    { "key": "comparison", "label": "Comparison rows", "type": "table", "target": { "blockId": "pr-compare", "path": "props.rows" },
-      "ui": { "preview": { "title": "feature", "subtitle": "group" }, "itemLabel": "Row" },
-      "config": { "fields": [
-        { "key": "group", "label": "Group", "type": "text" },
-        { "key": "feature", "label": "Feature", "type": "text" },
-        { "key": "starter", "label": "Starter", "type": "text" },
-        { "key": "growth", "label": "Growth", "type": "text" },
-        { "key": "scale", "label": "Scale", "type": "text" }
-      ] } },
-    { "key": "fineprint", "label": "Fine print", "type": "text", "target": { "blockId": "pr-fineprint", "path": "props.html" } }
-  ]
-}
-```
-
-A `table` prop targets `props.rows` of a `section` block whose children mirror one row. On a
-code-built site the repo file draws the band: record it with `set_component_source` as soon as it
-exists.
-
-Value (`compose_pages`; one instance, keyed by prop key):
-
-```json
-{
-  "pages": [ { "slug": "pricing", "blockJson": [
-    { "type": "component", "id": "pricing-01", "props": {
-      "componentId": "<id returned by create_component>",
-      "overrides": {
-        "eyebrow": "Pricing",
-        "heading": "Plans that grow with your calendar",
-        "saving": "Save 20%",
-        "plans": [
-          { "name": "Starter", "audience": "For solo creators", "monthly": 0, "yearly": 0,
-            "features": [ { "line": "3 social accounts" }, { "line": "30 scheduled posts a month" } ],
-            "ctaLabel": "Start free", "ctaUrl": "https://app.cadence.so/signup" },
-          { "name": "Growth", "audience": "For growing marketing teams", "badge": "Most popular",
-            "monthly": 30, "yearly": 24,
-            "features": [ { "line": "15 social accounts" }, { "line": "Approval workflows" }, { "line": "AI caption drafts" } ],
-            "ctaLabel": "Start 14-day trial", "ctaUrl": "https://app.cadence.so/signup?plan=growth" },
-          { "name": "Scale", "audience": "For agencies and brands", "priceLabel": "Let's talk",
-            "features": [ { "line": "Unlimited accounts" }, { "line": "SSO and audit log" } ],
-            "ctaLabel": "Talk to sales", "ctaUrl": "/contact-sales" }
-        ],
-        "comparison": [
-          { "group": "Usage", "feature": "Scheduled posts", "starter": "30 a month", "growth": "Unlimited", "scale": "Unlimited" },
-          { "group": "Features", "feature": "AI caption drafts", "starter": "No", "growth": "50 a month", "scale": "Yes" }
-        ],
-        "fineprint": "Prices in USD, excluding tax. Yearly plans are billed once a year."
-      } } }
-  ] } ]
-}
-```
-
-Bound template (the Growth card and one comparison row; `pricing-01` is the instance id):
-
-```html
-<section class="pricing" id="pricing" data-bcms-block="pricing-01">
-  <h2 data-bcms-field="pricing-01__overrides.heading" data-bcms-kind="text">Plans that grow with your calendar</h2>
-  <article class="plan plan--featured">
-    <span class="ribbon" data-bcms-field="pricing-01__overrides.plans[1].badge" data-bcms-kind="text">Most popular</span>
-    <h3 data-bcms-field="pricing-01__overrides.plans[1].name" data-bcms-kind="text">Growth</h3>
-    <p class="price"><span class="amount">$<span data-bcms-field="pricing-01__overrides.plans[1].yearly">24</span></span><span class="per">/mo</span></p>
-    <ul class="checks">
-      <li data-bcms-field="pricing-01__overrides.plans[1].features[0].line" data-bcms-kind="text">15 social accounts</li>
-    </ul>
-    <a class="btn btn-primary" href="https://app.cadence.so/signup?plan=growth"
-      data-bcms-props="pricing-01__overrides.plans[1].ctaUrl|url|href">
-      <span data-bcms-field="pricing-01__overrides.plans[1].ctaLabel" data-bcms-kind="text">Start 14-day trial</span></a>
-  </article>
-  <table class="compare"><tbody>
-    <tr><th scope="row" data-bcms-field="pricing-01__overrides.comparison[0].feature" data-bcms-kind="text">Scheduled posts</th>
-      <td data-bcms-field="pricing-01__overrides.comparison[0].starter" data-bcms-kind="text">30 a month</td>
-      <td data-bcms-field="pricing-01__overrides.comparison[0].growth" data-bcms-kind="text">Unlimited</td>
-      <td data-bcms-field="pricing-01__overrides.comparison[0].scale" data-bcms-kind="text">Unlimited</td></tr>
-  </tbody></table>
-</section>
-```
-
-- Use the package `bind` and `bindProps` helpers inside an instance; they produce these addresses.
-  A definition block id (`pr-heading`) is shared by every instance and binds to nothing.
-- Bind the digits, not `$24/mo`. The symbol and the period come from the template. Bind the price
-  on screen; when the switch shows monthly, the address is `.monthly`.
-- A cell the template draws as an icon ("Yes", "No") is not bound: it is edited in the side panel.
-- A comparison written as prose instead belongs in a `richtext` prop as a Portable Text `table`
-  ([portable-text.md](portable-text.md)); then the wrapper of that one value is the bound element.
-
-A typed table is available on both sides. On a component each `table` column is one sub-field
-with its own type (`number`, `boolean`, `url`, ...), as `monthly` and `ctaUrl` are above. On a
-model it is a `repeater` (stored as an `array` with `config.zones.repeatable.fields`): one field
-per column, of any field type, `minItems` / `maxItems` on the repeatable zone, and
-`ui.layout: "table"` to edit the rows as a grid. To key rows to plan ids, give the model a `text`
-column with `unique: true`. A value only a developer may change is a model field with
-`readOnly: "developer"` and a `lockReason`.
-
-Not available today: a per-cell type (a column has one type for every row), and a caption,
-footnotes or row groups as parts of the table (model them as fields beside it, as `group` and
-`fineprint` are here). Offer markup: no JSON-LD is built from prices. Paste it as `schema` on
-`update_page` when the page needs it. A fourth plan in the comparison is a new sub-field, a schema
-change.
-
-## 4. Testimonials kept as a collection
-
-Source: three quote cards on a home page. The same quotes also show on the pricing and product
-pages.
-
-```html
-<section class="testimonials bg-stone-50 py-24">
-  <p class="eyebrow">Customers</p>
-  <h2 class="text-3xl">Teams that stopped chasing spreadsheets</h2>
-  <div class="cards grid gap-6 md:grid-cols-3">
-    <figure class="t-card">
-      <div class="stars" role="img" aria-label="5 out of 5 stars">★★★★★</div>
-      <blockquote><p>&ldquo;We closed March in a day and a half. Our auditors asked what changed.&rdquo;</p></blockquote>
-      <figcaption>
-        <img class="avatar" src="/img/people/dana-ruiz.jpg" alt="" width="48" height="48">
-        <span class="name">Dana Ruiz</span><span class="role">Controller, Brightwell Foods</span>
-      </figcaption>
-    </figure>
-    <!-- Omar Haddad, VP Finance, Northgate Logistics, 5 stars; Mei Tanaka, Finance Lead, Alder Studio, 4 stars, no photo -->
-  </div>
-  <a class="btn btn-outline" href="/customers">Read all customer stories</a>
-</section>
-```
-
-Reasoning:
-
-1. Search the site before modelling rows inside the section. The quotes repeat on three pages, so
-   each quote is one entry of a content model and is written once.
-2. Per entry: the quote without the curly quotes (the template adds them), name, role and company
-   split at the comma, photo, and the rating read from `aria-label`. Add a consent switch:
-   publishing a person's words needs their permission.
-3. The avatar's `alt=""` is correct: the name sits beside it. Keep the alt text empty.
-4. The section keeps its own eyebrow, heading and button. How it gets its three quotes depends on
-   where it lives (table below).
-
-Schema (`create_content_model`), then the home page's own fields:
-
-```json
-{
-  "name": "Testimonial",
-  "slug": "testimonial",
-  "urlPattern": "/customers/:slug",
-  "fields": [
-    { "key": "quote", "label": "Quote", "type": "text", "richText": false, "required": true,
-      "helpText": "Without quotation marks; the page adds them." },
-    { "key": "name", "label": "Name", "type": "text", "richText": false, "required": true },
-    { "key": "role", "label": "Role", "type": "text", "richText": false },
-    { "key": "company", "label": "Company", "type": "text", "richText": false },
-    { "key": "photo", "label": "Photo", "type": "image" },
-    { "key": "rating", "label": "Rating", "type": "number", "config": { "min": 1, "max": 5, "step": 1 } },
-    { "key": "consent", "label": "Permission to publish", "type": "boolean" }
-  ]
-}
-```
-
-```json
-[
-  { "key": "testimonials_eyebrow", "label": "Eyebrow", "type": "text", "richText": false },
-  { "key": "testimonials_title", "label": "Heading", "type": "text", "richText": false },
-  { "key": "testimonials_picks", "label": "Testimonials", "type": "multi-reference",
-    "config": { "contentModelId": "<testimonial model id>", "min": 3, "max": 9 },
-    "helpText": "Pick 3, 6 or 9 so the grid has no gaps." },
-  { "key": "testimonials_cta", "label": "Button", "type": "button" }
-]
-```
-
-Value: entries first (`create_content_entries`, drafts, ids come back), then the page:
-
-```json
-{
-  "contentModelId": "<testimonial model id>",
-  "entries": [
-    { "slug": "dana-ruiz", "data": { "quote": "We closed March in a day and a half. Our auditors asked what changed.",
-        "name": "Dana Ruiz", "role": "Controller", "company": "Brightwell Foods",
-        "photo": { "url": "/img/people/dana-ruiz.jpg", "altText": "" }, "rating": 5, "consent": true } },
-    { "slug": "omar-haddad", "data": { "quote": "Matching used to eat two people for a week. Now it is a coffee.",
-        "name": "Omar Haddad", "role": "VP Finance", "company": "Northgate Logistics",
-        "photo": { "url": "/img/people/omar-haddad.jpg", "altText": "" }, "rating": 5, "consent": true } },
-    { "slug": "mei-tanaka", "data": { "quote": "The audit log alone paid for it.",
-        "name": "Mei Tanaka", "role": "Finance Lead", "company": "Alder Studio", "rating": 4, "consent": true } }
-  ]
-}
-```
-
-```json
-{
-  "pageId": "<home page id>",
-  "data": {
-    "testimonials_eyebrow": "Customers",
-    "testimonials_title": "Teams that stopped chasing spreadsheets",
-    "testimonials_picks": ["<dana entry id>", "<omar entry id>", "<mei entry id>"],
-    "testimonials_cta": { "label": "Read all customer stories", "href": "/customers", "variant": "outline" }
-  }
-}
-```
-
-A reference value is the entry id as a string; a multi-reference is a list of them. An id that
-does not exist is refused with a 400 ("ref_missing"), so create the entries before the page value.
-
-How a band shows the entries, by where it lives:
-
-| Where | What production supports |
-|---|---|
-| A code-built page (this example) | A `multi-reference` page field holds the picked ids; the template reads the entries and draws the cards |
-| The collection's own dynamic page (`/customers`) | A `collection` block: `cardComponentId`, `limit` (1 to 200), `order` (`newest` or `oldest`), `emptyText` |
-| A component placed on several pages | A `table` prop filled per instance. The quotes are then copies: a change to one entry is repeated by hand on each instance |
-
-Bound template (the section's own values; one card shown):
-
-```html
-<p class="eyebrow" data-bcms-field="testimonials_eyebrow" data-bcms-kind="text">Customers</p>
-<h2 class="text-3xl" data-bcms-field="testimonials_title" data-bcms-kind="text">Teams that stopped chasing spreadsheets</h2>
-<div class="cards grid gap-6 md:grid-cols-3">
-  <figure class="t-card">
-    <div class="stars" role="img" aria-label="5 out of 5 stars">★★★★★</div>
-    <blockquote><p>&ldquo;We closed March in a day and a half. Our auditors asked what changed.&rdquo;</p></blockquote>
-    <figcaption><img class="avatar" src="/img/people/dana-ruiz.jpg" alt=""><span class="name">Dana Ruiz</span></figcaption>
-  </figure>
-</div>
-```
-
-- The cards carry no page binding. Their words belong to the entries and are edited there, once,
-  for every page that shows them. The picked list is changed in the side panel.
-- Draw the stars from `rating`; never store the glyphs.
-
-One chosen entry on a hosted page is a `collection` block, not a prop: `source: { modelId }`,
-`pinnedIds: ["<entry id>"]`, `limit: 1` and `cardComponentId` naming the card that draws it. Pinned
-entries come first, so the limit keeps exactly that one.
-
-Not available today: a component prop that references entries (there is no reference prop type; it
-would save and render nothing). A listing chosen by tag or filter on a route the repo's code
-renders: the `collection` block with `source`, `filters` and `sort` is drawn by the hosted
-renderer only, so there a "latest for this product" list is a query in the site's code. A
-decorative flag on an image VALUE: an empty `altText` is the signal for one placement;
-`update_media` `decorative: true` marks the asset itself.
-
-## 5. FAQ accordion with FAQPage markup
-
-Source: a help band built from `<details>`, with hand-written FAQPage JSON-LD beside it.
-
-```html
-<section class="faq" id="faq">
-  <h2>Questions, answered</h2>
-  <p>Straight answers about billing, data and switching tools.</p>
-  <details class="faq-item" open>
-    <summary><h3>Can I cancel at any time?</h3><svg class="chevron" aria-hidden="true"/></summary>
-    <div class="faq-item__body"><p>Yes. Cancel from <strong>Settings &gt; Billing</strong> and you keep access until the end of the period.</p></div>
-  </details>
-  <details class="faq-item">
-    <summary><h3>Where is my data stored?</h3><svg class="chevron" aria-hidden="true"/></summary>
-    <div class="faq-item__body"><p>In the EU or the US, your choice at sign-up. Read the <a href="/security">security overview</a>.</p></div>
-  </details>
-  <details class="faq-item">
-    <summary><h3>How do I move from spreadsheets?</h3><svg class="chevron" aria-hidden="true"/></summary>
-    <div class="faq-item__body"><p>Most teams switch in an afternoon:</p>
-      <ol><li>Connect your bank.</li><li>Import last month's CSV.</li><li>Invite your team.</li></ol></div>
-  </details>
-  <p class="faq__more">Still stuck? <a href="/support">Talk to support</a></p>
-</section>
-<script type="application/ld+json">{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[...]}</script>
-```
-
-Reasoning:
-
-1. Repeated `<details>` with a question and an answer, specific to this page: a repeater in the
-   page's fields. Move to a collection only when the same questions repeat on several pages.
-2. The question is a plain string; the `<h3>` and the chevron belong to the template. The answer
-   carries bold text, a link and a list: rich text, narrowed to what answers use.
-3. `open` on the first item is behaviour. It stays in the template.
-4. "Talk to support" is a `button` field. "Still stuck?" is fixed template copy.
-5. Delete the hand-written `<script type="application/ld+json">` and set the page's schema type
-   instead. Name the row keys so they contain `question` and `answer`: the FAQPage builder finds
-   the first list on the page whose rows have both.
-
-Schema:
-
-```json
-[
-  { "key": "faq_title", "label": "Heading", "type": "text", "richText": false },
-  { "key": "faq_intro", "label": "Intro", "type": "text", "richText": false },
-  { "key": "faq_items", "label": "Questions", "type": "repeater",
-    "ui": { "preview": { "title": "faq_question" }, "itemLabel": "Question" },
-    "fields": [
-      { "key": "faq_question", "label": "Question", "type": "text", "richText": false, "required": true },
-      { "key": "faq_answer", "label": "Answer", "type": "richtext", "required": true,
-        "config": { "accept": ["p", "b", "i", "link", "ul", "ol"] } }
-    ] },
-  { "key": "faq_support", "label": "Support link", "type": "button" }
-]
-```
-
-Value (`set_page_content` `data`; each answer is a Portable Text array, shown below):
-
-```jsonc
-{
-  "faq_title": "Questions, answered",
-  "faq_intro": "Straight answers about billing, data and switching tools.",
-  "faq_items": { "repeatable": [
-    { "faq_question": "Can I cancel at any time?", "faq_answer": [ /* one paragraph, "Settings > Billing" marked strong */ ] },
-    { "faq_question": "Where is my data stored?", "faq_answer": [ /* array A */ ] },
-    { "faq_question": "How do I move from spreadsheets?", "faq_answer": [ /* array B */ ] }
-  ] },
-  "faq_support": { "label": "Talk to support", "href": "/support", "variant": "link" }
-}
-```
-
-Array A, a paragraph with a link:
-
-<!-- pt-example -->
-```json
-[
-  { "_type": "block", "_key": "a2p1", "style": "normal",
-    "markDefs": [{ "_type": "link", "_key": "a2l1", "href": "/security" }],
-    "children": [
-      { "_type": "span", "_key": "a2s1", "text": "In the EU or the US, your choice at sign-up. Read the ", "marks": [] },
-      { "_type": "span", "_key": "a2s2", "text": "security overview", "marks": ["a2l1"] },
-      { "_type": "span", "_key": "a2s3", "text": ".", "marks": [] }
-    ] }
-]
-```
-
-Array B, a paragraph then a flat numbered list:
-
-<!-- pt-example -->
-```json
-[
-  { "_type": "block", "_key": "a3p1", "style": "normal", "markDefs": [],
-    "children": [{ "_type": "span", "_key": "a3s1", "text": "Most teams switch in an afternoon:", "marks": [] }] },
-  { "_type": "block", "_key": "a3i1", "style": "normal", "listItem": "number", "level": 1, "markDefs": [],
-    "children": [{ "_type": "span", "_key": "a3s2", "text": "Connect your bank.", "marks": [] }] },
-  { "_type": "block", "_key": "a3i2", "style": "normal", "listItem": "number", "level": 1, "markDefs": [],
-    "children": [{ "_type": "span", "_key": "a3s3", "text": "Import last month's CSV.", "marks": [] }] },
-  { "_type": "block", "_key": "a3i3", "style": "normal", "listItem": "number", "level": 1, "markDefs": [],
-    "children": [{ "_type": "span", "_key": "a3s4", "text": "Invite your team.", "marks": [] }] }
-]
-```
-
-Structured data (`update_page`):
-
-```json
-{ "pageId": "<page id>", "schemaType": "FAQPage" }
-```
-
-Bound template (second item):
-
-```html
-<details class="faq-item">
-  <summary><h3 data-bcms-field="faq_items[1].faq_question" data-bcms-kind="text">Where is my data stored?</h3>
-    <svg class="chevron" aria-hidden="true"/></summary>
-  <div class="faq-item__body" data-bcms-field="faq_items[1].faq_answer" data-bcms-kind="richtext">
-    <p>In the EU or the US, your choice at sign-up. Read the <a href="/security">security overview</a>.</p>
-  </div>
-</details>
-```
-
-- The question binds on the `<h3>`, not the `<summary>`: a save on the summary would erase the
-  chevron.
-- `.faq-item__body` renders nothing but the answer, so it is the answer's element. If it also held
-  a "Was this helpful?" row, wrap the answer in its own `<div>` and bind that.
-- A paragraph inside an answer is addressed `faq_items[1].faq_answer#a2p1`; keep `_key` values
-  stable when you rewrite an answer, and write the whole field, never one block.
-
-Not available today: FAQPage markup that appears on its own. Without `schemaType: "FAQPage"` the
-page gets WebPage. An "open several at once" setting has no field type of its own; if editors
-need it, add a `boolean` field and have the template read it.
-
-## 9. Bento grid with per-cell sizes
-
-Source: the cookware brand's home page. The kit's `core-bento` entry is this shape, and
-`bento-feature-showcase` is its responsive long form ([kit-scenarios.md](kit-scenarios.md)).
-
-```html
-<section class="bento" id="field">
-  <p class="eyebrow">In the field</p>
-  <h2>Made to be handed down.</h2>
-  <div class="bento__grid grid grid-cols-4 gap-6">
-    <figure class="cell col-span-2 row-span-2 cell--dark">
-      <img src="/img/sierra-dawn-2400.jpg" alt="Dawn over a Sierra camp, kettle steaming" width="2400" height="2400">
-      <figcaption>Three nights in the Sierra</figcaption>
-    </figure>
-    <div class="cell cell--brand"><i class="ti ti-flame" aria-hidden="true"></i>
-      <span class="stat__value">120k+</span><span class="stat__label">Fires cooked over</span></div>
-    <div class="cell"><i class="ti ti-star" aria-hidden="true"></i>
-      <span class="stat__value">4.9</span><span class="stat__label">Average review</span></div>
-    <blockquote class="cell col-span-2"><p>Our restaurant runs four Ember ovens over live fire every night.</p>
-      <cite>Chef Amara Osei, Hearth &amp; Ash, Portland</cite></blockquote>
-  </div>
-</section>
-```
-
-Reasoning:
-
-1. The grid's children differ in shape (an image, two stats, a quote) and in size. Different
-   shapes chosen by the editor are slot children, not rows of one list.
-2. Each cell's size and surface belong to its place in this grid, not to the cell. Reading
-   `col-span-2 row-span-2` and `cell--dark` into the image tile's own props would carry a
-   meaningless span to every other page that reuses the tile. They go in the slot's settings.
-3. Size is a small set of presets (1 × 1, 2 × 1, 1 × 2, 2 × 2), so it is a select, never a free
-   column number. If the source's spans do not fit four presets, it is the per-cell grid
-   (`grid-cell-layout`), not a bento.
-4. The four-column versus three-column layout is a variant: a second component sharing the
-   `sectionType`, with the same prop keys.
-5. The icons and the gap between cells are design: they stay in the template's classes.
-
-Schema: one component per tile kind (`create_component`, then `publish_component`). The stat tile:
-
-```json
-{
-  "name": "Stat tile",
-  "slug": "stat-tile",
-  "category": "content",
-  "description": "A big number with a short label.",
-  "blockJson": [
-    { "type": "section", "id": "stat-root", "props": { "children": [
-      { "type": "text", "id": "stat-value", "props": { "html": "" } },
-      { "type": "text", "id": "stat-label", "props": { "html": "" } }
-    ] } }
-  ],
-  "props": [
-    { "key": "value", "label": "Number", "type": "text", "target": { "blockId": "stat-value", "path": "props.html" } },
-    { "key": "label", "label": "Label", "type": "text", "target": { "blockId": "stat-label", "path": "props.html" } }
-  ]
-}
-```
-
-The image tile (`image`, `caption`) and the quote tile (`quote`, `author`, `role`) are built the
-same way. Then the grid, whose `cells` slot lists them:
-
-```json
-{
-  "name": "Bento grid",
-  "slug": "bento-grid",
-  "sectionType": "bento",
-  "category": "section",
-  "description": "A mosaic of image, stat and quote cells, each with its own size and surface.",
-  "blockJson": [
-    { "type": "section", "id": "bento-root", "props": { "children": [
-      { "type": "text", "id": "bento-eyebrow", "props": { "html": "" } },
-      { "type": "heading", "id": "bento-title", "props": { "text": "", "level": 2 } },
-      { "type": "section", "id": "bento-cells", "props": { "children": [] } }
-    ] } }
-  ],
-  "props": [
-    { "key": "eyebrow", "label": "Eyebrow", "type": "text", "target": { "blockId": "bento-eyebrow", "path": "props.html" } },
-    { "key": "heading", "label": "Heading", "type": "text", "target": { "blockId": "bento-title", "path": "props.text" } },
-    { "key": "cells", "label": "Cells", "type": "slot",
-      "target": { "blockId": "bento-cells", "path": "props.children" },
-      "config": {
-        "multiple": true, "minItems": 3, "maxItems": 9,
-        "componentIds": ["<image tile id>", "<stat tile id>", "<quote tile id>"],
-        "slotSettings": [
-          { "key": "span", "label": "Size", "type": "select", "defaultValue": "1x1",
-            "options": [
-              { "value": "1x1", "label": "Small" }, { "value": "2x1", "label": "Wide" },
-              { "value": "1x2", "label": "Tall" }, { "value": "2x2", "label": "Large" } ] },
-          { "key": "tone", "label": "Surface", "type": "select", "defaultValue": "light",
-            "options": [
-              { "value": "light", "label": "Light" }, { "value": "dark", "label": "Dark" },
-              { "value": "brand", "label": "Brand" } ] }
-        ] } }
-  ]
-}
-```
-
-Value: the instance, inside the page's whole `blockJson` (`update_page` with `ifMatch`, or
-`compose_pages`). Each cell names its tile component in `_type`, holds that tile's props at its
-root, and its place in the grid in `_settings`:
-
-```json
-{ "type": "component", "id": "home-bento", "props": { "componentId": "<bento grid id>", "overrides": {
-  "eyebrow": "In the field",
-  "heading": "Made to be handed down.",
-  "cells": [
-    { "_key": "g1", "_type": "<image tile id>", "_settings": { "span": "2x2", "tone": "dark" },
-      "image": "/img/sierra-dawn-2400.jpg", "caption": "Three nights in the Sierra" },
-    { "_key": "g2", "_type": "<stat tile id>", "_settings": { "span": "1x1", "tone": "brand" },
-      "value": "120k+", "label": "Fires cooked over" },
-    { "_key": "g3", "_type": "<stat tile id>", "_settings": { "span": "1x1", "tone": "light" },
-      "value": "4.9", "label": "Average review" },
-    { "_key": "g4", "_type": "<quote tile id>", "_settings": { "span": "2x1", "tone": "light" },
-      "quote": "Our restaurant runs four Ember ovens over live fire every night.",
-      "author": "Chef Amara Osei", "role": "Hearth & Ash, Portland" }
-  ] } } }
-```
-
-Bound template: render the blocks with `BcmsBlocks`. Each cell arrives as a `component` block
-whose `props.slotSettings` holds its `_settings`; the template turns `span` and `tone` into its own
-grid and surface classes.
-
-```html
-<section data-bcms-block="home-bento">
-  <p data-bcms-field="home-bento__overrides.eyebrow" data-bcms-kind="text">In the field</p>
-  <h2 data-bcms-field="home-bento__overrides.heading" data-bcms-kind="text">Made to be handed down.</h2>
-  <div class="bento__grid grid grid-cols-4 gap-6">
-    <figure class="cell col-span-2 row-span-2 cell--dark">…</figure>
-  </div>
-</section>
-```
-
-- A `_settings` value that does not fit the slot's `slotSettings` is refused, naming the cell's
-  `_key`; a slot with no `slotSettings` takes no `_settings` at all.
-- `_key` is the cell's identity: keep it stable across reorders.
-- Publish every tile component before the grid: a draft child renders nothing.
-- A cell's copy is edited in the placement's `cells` list, not by clicking it on the canvas
-  ([components.md](components.md) §1).
-
-Not available today: spans that depend on the variant's column count (validate them yourself),
-per-breakpoint spans, and a phone order per cell.
-
-## Checks after any example
-
-1. Read back what you wrote: `get_page`, `get_component` or `get_layout`. A richtext value comes
-   back as an envelope, an image as the resolved asset, a repeater as `{ repeatable }`.
-2. `get_site_composition`: every placed component is published and no required prop is empty.
-3. After the next release, `get_binding_report` for the route: no unmatched path for the fields
-   you bound, and the mode you expect.
-4. Edit one value of each bound kind in the Visual Editor (a text, a link, an image, a body
-   block) and confirm only that element changed.
-5. Publishing needs the user's authorization. Say what is still a draft.
+---
+title: "Worked examples"
+description: "Six conversions from source HTML to a production schema, a production value and a bound template: hero, feature grid, pricing with a comparison table, testimonials as a collection, FAQ with FAQPage markup, bento grid with per-cell sizes."
+---
+
+# Worked examples: source HTML to schema, value and bound template
+
+Each example runs the same five steps: the source markup (trimmed), what it is and why, the
+schema as the write tool takes it, the value as the write tool takes it, and the template with
+its binding attributes. Copy the shape, never the customer's words. Rules behind the shapes:
+[content-modeling.md](content-modeling.md), [components.md](components.md),
+[bindings.md](bindings.md), [portable-text.md](portable-text.md). Examples 6 to 8 continue in
+[worked-examples-advanced.md](worked-examples-advanced.md).
+
+## Contents
+
+- [Which shape each example uses](#which-shape-each-example-uses)
+- [1. Hero with two buttons and a background image](#1-hero-with-two-buttons-and-a-background-image)
+- [2. Feature grid with icons](#2-feature-grid-with-icons)
+- [3. Pricing plans with a comparison table](#3-pricing-plans-with-a-comparison-table)
+- [4. Testimonials kept as a collection](#4-testimonials-kept-as-a-collection)
+- [5. FAQ accordion with FAQPage markup](#5-faq-accordion-with-faqpage-markup)
+- [9. Bento grid with per-cell sizes](#9-bento-grid-with-per-cell-sizes)
+- [Checks after any example](#checks-after-any-example)
+- Examples 6 to 8 (blog post as an entry, mega menu in the Global Layout, tabs holding columns
+  of cards): [worked-examples-advanced.md](worked-examples-advanced.md)
+
+## Which shape each example uses
+
+Production stores content in four places. Pick by what the markup is, then follow that example.
+
+| Markup | Stored as | Schema tool | Value tool | Address on the page | Example |
+|---|---|---|---|---|---|
+| A band one page owns | Page fields, keys prefixed by section | `create_page` `fields`, `add_field` | `set_page_content` | `data-bcms-field="<key>"` | 1, 2, 5 |
+| A band reused or with variants | Component with props | `create_component` | `compose_pages` (an instance per page) | `<instanceId>__overrides.<key>` | 3 |
+| Records that repeat on one route | Content model and entries | `create_content_model` | `create_content_entry` | the entry's field key | 4, 6 (advanced) |
+| Header, footer, promo bar | Global Layout Section | `update_layout` | `update_layout` | `data-bcms-layout-field` | 7 (advanced) |
+| A one-off band built from blocks | `section` block with child blocks | `update_page` `blockJson` | the same call | `<blockId>__<prop>` | 8 (advanced) |
+| Cells of different kinds, each with its own size | Component with a `slot` list and `slotSettings` | `create_component` | `compose_pages` | `<instanceId>__overrides.<key>` | 9 |
+
+Rules that hold in every example:
+
+- A key is unique in its whole model, so a page field carries its section: `"hero_title"`,
+  `"faq_title"`. Prop keys and sub-field keys live inside one component and stay short.
+- A field of type `text` is created as rich text. Send `richText: false` for every plain string
+  (a title, an eyebrow, a name, an icon name), then write it as a bare string.
+- A repeater value is `{ "repeatable": [ ...rows ] }`; a row is addressed `<key>[<n>].<childKey>`.
+- Bind the element that renders the value. Never a wrapper, never a list container.
+- `set_page_content` merges by top-level key. `compose_pages` and `update_page` `blockJson`
+  replace the page's whole block array: read `get_page` first and send every block back.
+
+## 1. Hero with two buttons and a background image
+
+Source: a freight-tracking home page.
+
+```html
+<section class="hero relative isolate overflow-hidden" id="top">
+  <picture class="absolute inset-0 -z-10">
+    <source type="image/avif" srcset="/img/hero-harbor-1280.avif 1280w, /img/hero-harbor-2560.avif 2560w">
+    <img src="/img/hero-harbor-1280.jpg" alt="Container cranes over a quiet harbor at dusk"
+      class="h-full w-full object-cover object-[50%_35%]" width="2560" height="1440">
+  </picture>
+  <div class="absolute inset-0 -z-10 bg-slate-950/50" aria-hidden="true"></div>
+  <div class="mx-auto max-w-6xl px-6 py-32 text-white">
+    <p class="text-sm uppercase text-teal-300">Freight visibility for mid-size shippers</p>
+    <h1 class="mt-4 text-5xl font-bold">Know where every container is before your customer asks.</h1>
+    <p class="mt-6 text-lg">Live ETAs from 140 carriers, delays flagged before they cost you, and one shared view for ops and sales.</p>
+    <a href="/demo" class="btn btn-primary">Book a demo <svg class="icon-arrow-right" aria-hidden="true"/></a>
+    <a href="https://app.kestrelfreight.com/signup" class="btn btn-ghost">Start free trial</a>
+    <p class="mt-8 text-sm"><span class="stars" role="img" aria-label="Rated 4.8 out of 5">★★★★★</span> 4.8 on G2 from 310 reviews</p>
+  </div>
+</section>
+```
+
+Reasoning:
+
+1. One `<h1>`, a lede, two links styled as buttons, a photo behind the copy: the page's opening
+   band. Other pages write their own hero copy, so this is page fields, not chrome.
+2. The uppercase line, the heading and the paragraph carry no links or emphasis: three plain
+   strings.
+3. Each `<a class="btn">` is one `button` field. Label, link and look travel together; the
+   trailing arrow is the button's `arrow`, not content.
+4. The `<picture>` is one `image` field. Store the largest source once and copy the `alt`. The CSS
+   `object-position: 50% 35%` is the focal point: divide by 100, so `{ x: 0.5, y: 0.35 }`.
+5. The stars are drawn from the number. Store `4.8` and the label; never the glyphs.
+6. The scrim, the padding and the teal colour are design. They stay in the site's classes.
+
+Schema (`create_page` `fields`, or one `add_field` with `pageId` per field):
+
+```json
+[
+  { "key": "hero_eyebrow", "label": "Eyebrow", "type": "text", "richText": false },
+  { "key": "hero_title", "label": "Heading", "type": "text", "richText": false, "required": true },
+  { "key": "hero_lede", "label": "Supporting text", "type": "text", "richText": false },
+  { "key": "hero_primary", "label": "Primary button", "type": "button" },
+  { "key": "hero_secondary", "label": "Secondary button", "type": "button" },
+  { "key": "hero_image", "label": "Background image", "type": "image",
+    "helpText": "Fills the whole band behind the text. Use a photo at least 2560 px wide." },
+  { "key": "hero_rating", "label": "Rating", "type": "number", "config": { "min": 0, "max": 5, "step": 0.1 },
+    "ui": { "control": "rating" } },
+  { "key": "hero_rating_label", "label": "Rating source", "type": "text", "richText": false }
+]
+```
+
+Value (`set_page_content`):
+
+```json
+{
+  "pageId": "<home page id>",
+  "data": {
+    "hero_eyebrow": "Freight visibility for mid-size shippers",
+    "hero_title": "Know where every container is before your customer asks.",
+    "hero_lede": "Live ETAs from 140 carriers, delays flagged before they cost you, and one shared view for ops and sales.",
+    "hero_primary": { "label": "Book a demo", "href": "/demo", "arrow": true },
+    "hero_secondary": { "label": "Start free trial", "href": "https://app.kestrelfreight.com/signup" },
+    "hero_image": {
+      "url": "/img/hero-harbor-2560.jpg",
+      "altText": "Container cranes over a quiet harbor at dusk",
+      "focal": { "x": 0.5, "y": 0.35 }
+    },
+    "hero_rating": 4.8,
+    "hero_rating_label": "on G2 from 310 reviews"
+  }
+}
+```
+
+Bound template (classes unchanged, shortened here):
+
+```html
+<section class="hero ..." id="top">
+  <picture class="absolute inset-0 -z-10">
+    <img src="/img/hero-harbor-1280.jpg" alt="Container cranes over a quiet harbor at dusk"
+      data-bcms-field="hero_image" data-bcms-kind="image">
+  </picture>
+  <div class="absolute inset-0 -z-10 bg-slate-950/50" aria-hidden="true"></div>
+  <p data-bcms-field="hero_eyebrow" data-bcms-kind="text">Freight visibility for mid-size shippers</p>
+  <h1 data-bcms-field="hero_title" data-bcms-kind="text">Know where every container is before your customer asks.</h1>
+  <p data-bcms-field="hero_lede" data-bcms-kind="text">Live ETAs from 140 carriers, ...</p>
+  <a class="btn btn-primary" href="/demo" data-bcms-button="hero_primary"
+    data-bcms-props="hero_primary.href|url|href">
+    <span data-bcms-field="hero_primary.label" data-bcms-kind="text">Book a demo</span></a>
+  <a class="btn btn-ghost" href="https://app.kestrelfreight.com/signup" data-bcms-button="hero_secondary"
+    data-bcms-props="hero_secondary.href|url|href">
+    <span data-bcms-field="hero_secondary.label" data-bcms-kind="text">Start free trial</span></a>
+  <p><span class="stars" role="img" aria-label="Rated 4.8 out of 5">★★★★★</span>
+    <span data-bcms-field="hero_rating">4.8</span>
+    <span data-bcms-field="hero_rating_label" data-bcms-kind="text">on G2 from 310 reviews</span></p>
+</section>
+```
+
+- The image binding sits on the `<img>`, not the `<picture>`. The alt text travels in the image
+  value (`altText`): a publish writes it to the bound element's `alt`. When `get_conversion_brief`
+  lists a separate alt path, declare that path in `data-bcms-props` with kind `text`.
+- Neither button value names a `variant`: the anchors keep the site's own `btn-primary` and
+  `btn-ghost`, and the release reads those two looks into the project's Button family.
+- An `href` is kind `url`, never `text`. The label gets its own `<span>` so a save does not erase
+  the arrow; the arrow is drawn by `BcmsButton` ([components.md](components.md)), so remove the
+  hand-written `<svg>` once the button renders through it.
+- A number shown as text binds with no kind. `number` is a kind only inside `data-bcms-props`.
+- The image value's `focal` frames this placement only; the asset's own focal point is untouched.
+
+Not available today: an overlay, height or theme token on the section. The scrim and spacing stay
+in the template's classes and change in code.
+
+## 2. Feature grid with icons
+
+Source: a finance SaaS product page.
+
+```html
+<section class="features py-24" aria-labelledby="features-title">
+  <span class="kicker">Why teams switch</span>
+  <h2 id="features-title">Everything your finance team asked for, in one close.</h2>
+  <p class="lede">Ledgerly connects to your bank, your payroll and your ERP, then does the matching for you.</p>
+  <ul class="grid gap-8 md:grid-cols-3" role="list">
+    <li class="feature-card">
+      <span class="icon-tile"><svg class="lucide lucide-zap" aria-hidden="true"><use href="#zap"/></svg></span>
+      <h3>Close in two days</h3>
+      <p>Auto-matching clears 92% of transactions before anyone opens a spreadsheet.</p>
+      <a class="text-link" href="/product/reconciliation">How matching works <span aria-hidden="true">→</span></a>
+    </li>
+    <li class="feature-card">
+      <span class="icon-tile"><svg class="lucide lucide-shield-check" aria-hidden="true"><use href="#shield-check"/></svg></span>
+      <h3>Audit-ready by default</h3>
+      <p>Every change is logged with who, when and why, so year-end takes hours.</p>
+    </li>
+    <!-- third card: plug, "40 native integrations", link to /integrations -->
+  </ul>
+  <a class="btn btn-outline mt-12" href="/product">Explore the product</a>
+</section>
+```
+
+Reasoning:
+
+1. A heading group, then same-shaped `<li>` cards: a repeater. The count and order are the
+   editor's; the three-column grid is the template's.
+2. Per card: the `<h3>` and the `<p>` are plain strings. The trailing link is optional, so the
+   second card leaves it empty. Never invent a link to fill the row.
+3. The icon is a sprite reference (`<use href="#zap"/>`), so the content is its name. Store the
+   name the site's own sprite uses (`zap`), as a plain string. An inline `<svg>` with its own
+   paths is different: that is an `image` field with `config: { "media": "icon" }`.
+4. The band's last button is a `button` field of its own, outside the repeater.
+
+Schema:
+
+```json
+[
+  { "key": "features_eyebrow", "label": "Eyebrow", "type": "text", "richText": false },
+  { "key": "features_title", "label": "Heading", "type": "text", "richText": false },
+  { "key": "features_intro", "label": "Intro", "type": "text", "richText": false },
+  { "key": "features_items", "label": "Features", "type": "repeater",
+    "ui": { "preview": { "title": "features_item_title" }, "itemLabel": "Feature" },
+    "fields": [
+      { "key": "features_item_icon", "label": "Icon", "type": "text", "richText": false,
+        "helpText": "Icon name from the site's sprite, lowercase with hyphens: zap, shield-check, plug." },
+      { "key": "features_item_title", "label": "Title", "type": "text", "richText": false },
+      { "key": "features_item_body", "label": "Description", "type": "text", "richText": false },
+      { "key": "features_item_link", "label": "Link", "type": "button" }
+    ] },
+  { "key": "features_cta", "label": "Button", "type": "button" }
+]
+```
+
+Value (`set_page_content` `data`):
+
+```json
+{
+  "features_eyebrow": "Why teams switch",
+  "features_title": "Everything your finance team asked for, in one close.",
+  "features_intro": "Ledgerly connects to your bank, your payroll and your ERP, then does the matching for you.",
+  "features_items": { "repeatable": [
+    { "features_item_icon": "zap", "features_item_title": "Close in two days",
+      "features_item_body": "Auto-matching clears 92% of transactions before anyone opens a spreadsheet.",
+      "features_item_link": { "label": "How matching works", "href": "/product/reconciliation", "variant": "link" } },
+    { "features_item_icon": "shield-check", "features_item_title": "Audit-ready by default",
+      "features_item_body": "Every change is logged with who, when and why, so year-end takes hours." },
+    { "features_item_icon": "plug", "features_item_title": "40 native integrations",
+      "features_item_body": "Banks, payroll and ERPs sync every hour without CSV exports.",
+      "features_item_link": { "label": "See integrations", "href": "/integrations", "variant": "link" } }
+  ] },
+  "features_cta": { "label": "Explore the product", "href": "/product", "variant": "outline" }
+}
+```
+
+Bound template (first card):
+
+```html
+<h2 id="features-title" data-bcms-field="features_title" data-bcms-kind="text">Everything your finance team asked for, in one close.</h2>
+<ul class="grid gap-8 md:grid-cols-3" role="list">
+  <li class="feature-card">
+    <span class="icon-tile"><svg class="lucide lucide-zap" aria-hidden="true"><use href="#zap"/></svg></span>
+    <h3 data-bcms-field="features_items[0].features_item_title" data-bcms-kind="text">Close in two days</h3>
+    <p data-bcms-field="features_items[0].features_item_body" data-bcms-kind="text">Auto-matching clears 92% ...</p>
+    <a class="text-link" href="/product/reconciliation" data-bcms-button="features_items[0].features_item_link"
+      data-bcms-props="features_items[0].features_item_link.href|url|href">
+      <span data-bcms-field="features_items[0].features_item_link.label" data-bcms-kind="text">How matching works</span>
+      <span aria-hidden="true">→</span></a>
+  </li>
+</ul>
+```
+
+- The `<ul>` carries no binding. Rows are added, removed and reordered in the side panel.
+- Emit an address only for a row that exists, and only for a link the row holds.
+- The icon `<svg>` is not bound: no field is read from text inside an SVG. The name is edited in
+  the side panel and the template turns it into the sprite reference.
+
+To make the icon editable, add a field of type `icon`: its value is a BetterCMS icon name or an
+uploaded icon, and a name off the set is refused. A component prop of type `icon` takes the same
+value ([components.md](components.md) §1). An inline SVG stays an `image` with `media: "icon"`.
+
+## 3. Pricing plans with a comparison table
+
+Source: a social scheduling SaaS. The same band sits on the pricing page and the home page, so
+it is a component.
+
+```html
+<section class="pricing" id="pricing">
+  <p class="eyebrow">Pricing</p>
+  <h2>Plans that grow with your calendar</h2>
+  <div class="billing-toggle" role="radiogroup" aria-label="Billing period">
+    <button role="radio" aria-checked="false" data-cycle="monthly">Monthly</button>
+    <button role="radio" aria-checked="true" data-cycle="yearly">Yearly <span class="pill">Save 20%</span></button>
+  </div>
+  <div class="plans grid md:grid-cols-3">
+    <article class="plan">
+      <h3>Starter</h3><p class="plan__for">For solo creators</p>
+      <p class="price"><span class="amount">$0</span></p>
+      <ul class="checks"><li>3 social accounts</li><li>30 scheduled posts a month</li></ul>
+      <a class="btn btn-outline" href="https://app.cadence.so/signup">Start free</a>
+    </article>
+    <article class="plan plan--featured">
+      <span class="ribbon">Most popular</span>
+      <h3>Growth</h3><p class="plan__for">For growing marketing teams</p>
+      <p class="price"><span class="amount" data-monthly="30" data-yearly="24">$24</span><span class="per">/mo</span></p>
+      <ul class="checks"><li>15 social accounts</li><li>Approval workflows</li><li>AI caption drafts</li></ul>
+      <a class="btn btn-primary" href="https://app.cadence.so/signup?plan=growth">Start 14-day trial</a>
+    </article>
+    <!-- Scale: "For agencies and brands", price "Let's talk", link /contact-sales -->
+  </div>
+  <table class="compare">
+    <thead><tr><th></th><th scope="col">Starter</th><th scope="col">Growth</th><th scope="col">Scale</th></tr></thead>
+    <tbody>
+      <tr class="group"><th colspan="4" scope="colgroup">Usage</th></tr>
+      <tr><th scope="row">Scheduled posts</th><td>30 a month</td><td>Unlimited</td><td>Unlimited</td></tr>
+      <tr class="group"><th colspan="4" scope="colgroup">Features</th></tr>
+      <tr><th scope="row">AI caption drafts</th><td><svg class="i-x" aria-label="Not included"/></td><td>50 a month</td><td><svg class="i-check" aria-label="Included"/></td></tr>
+    </tbody>
+  </table>
+  <p class="fineprint">Prices in USD, excluding tax. Yearly plans are billed once a year.</p>
+</section>
+```
+
+Reasoning:
+
+1. Plan cards and the comparison table share plan names and always show together: one section.
+2. Plans are same-shaped rows: one `table` prop. `data-monthly` and `data-yearly` give two
+   numbers; store numbers, never `$24/mo`. A price in words ("Let's talk") is its own text key,
+   shown when the numbers are empty.
+3. Each plan's check list is a list inside a row: a nested `table` whose rows hold one string.
+   That is the deepest a prop goes: the inner row takes scalars only.
+4. The comparison is a second `table` prop: one row object per feature, one text key per plan,
+   plus the group it sits under. The template prints a group row when `group` changes. Read
+   "Included" and "Not included" from `aria-label`, store "Yes" and "No", and let the template
+   draw the icon.
+5. A CTA inside a component is one `button` block that two props target (`text`, `url`).
+
+Schema (`create_component`; lands as a draft, then `publish_component`):
+
+```json
+{
+  "name": "Pricing / Three plans",
+  "slug": "pricing-three-plans",
+  "category": "conversion",
+  "sectionType": "Pricing",
+  "description": "Plan cards with monthly and yearly prices, then a feature comparison.",
+  "blockJson": [
+    { "type": "section", "id": "pr-root", "props": { "children": [
+      { "type": "text", "id": "pr-eyebrow", "props": { "html": "" } },
+      { "type": "heading", "id": "pr-heading", "props": { "text": "", "level": 2 } },
+      { "type": "text", "id": "pr-saving", "props": { "html": "" } },
+      { "type": "section", "id": "pr-plans", "label": "Plans", "props": { "children": [
+        { "type": "heading", "id": "pr-plan-name", "props": { "text": "", "level": 3 } },
+        { "type": "button", "id": "pr-plan-cta", "props": { "text": "", "href": "" } }
+      ] } },
+      { "type": "section", "id": "pr-compare", "label": "Comparison", "props": { "children": [
+        { "type": "heading", "id": "pr-compare-feature", "props": { "text": "", "level": 4 } }
+      ] } },
+      { "type": "text", "id": "pr-fineprint", "props": { "html": "" } }
+    ] } }
+  ],
+  "props": [
+    { "key": "eyebrow", "label": "Eyebrow", "type": "text", "target": { "blockId": "pr-eyebrow", "path": "props.html" } },
+    { "key": "heading", "label": "Heading", "type": "text", "target": { "blockId": "pr-heading", "path": "props.text" } },
+    { "key": "saving", "label": "Yearly saving badge", "type": "text", "target": { "blockId": "pr-saving", "path": "props.html" } },
+    { "key": "plans", "label": "Plans", "type": "table", "target": { "blockId": "pr-plans", "path": "props.rows" },
+      "ui": { "preview": { "title": "name" }, "itemLabel": "Plan" },
+      "config": { "fields": [
+        { "key": "name", "label": "Name", "type": "text" },
+        { "key": "audience", "label": "Who it is for", "type": "text" },
+        { "key": "badge", "label": "Badge", "type": "text" },
+        { "key": "monthly", "label": "Monthly price", "type": "number", "helpText": "Per month, billed monthly. Digits only." },
+        { "key": "yearly", "label": "Yearly price", "type": "number", "helpText": "Per month, when billed yearly. Digits only." },
+        { "key": "priceLabel", "label": "Price in words", "type": "text", "helpText": "Shown when both prices are empty." },
+        { "key": "features", "label": "Included", "type": "table", "fields": [
+          { "key": "line", "label": "Feature", "type": "text" }
+        ] },
+        { "key": "ctaLabel", "label": "Button label", "type": "text" },
+        { "key": "ctaUrl", "label": "Button link", "type": "url" }
+      ] } },
+    { "key": "comparison", "label": "Comparison rows", "type": "table", "target": { "blockId": "pr-compare", "path": "props.rows" },
+      "ui": { "preview": { "title": "feature", "subtitle": "group" }, "itemLabel": "Row" },
+      "config": { "fields": [
+        { "key": "group", "label": "Group", "type": "text" },
+        { "key": "feature", "label": "Feature", "type": "text" },
+        { "key": "starter", "label": "Starter", "type": "text" },
+        { "key": "growth", "label": "Growth", "type": "text" },
+        { "key": "scale", "label": "Scale", "type": "text" }
+      ] } },
+    { "key": "fineprint", "label": "Fine print", "type": "text", "target": { "blockId": "pr-fineprint", "path": "props.html" } }
+  ]
+}
+```
+
+A `table` prop targets `props.rows` of a `section` block whose children mirror one row. On a
+code-built site the repo file draws the band: record it with `set_component_source` as soon as it
+exists.
+
+Value (`compose_pages`; one instance, keyed by prop key):
+
+```json
+{
+  "pages": [ { "slug": "pricing", "blockJson": [
+    { "type": "component", "id": "pricing-01", "props": {
+      "componentId": "<id returned by create_component>",
+      "overrides": {
+        "eyebrow": "Pricing",
+        "heading": "Plans that grow with your calendar",
+        "saving": "Save 20%",
+        "plans": [
+          { "name": "Starter", "audience": "For solo creators", "monthly": 0, "yearly": 0,
+            "features": [ { "line": "3 social accounts" }, { "line": "30 scheduled posts a month" } ],
+            "ctaLabel": "Start free", "ctaUrl": "https://app.cadence.so/signup" },
+          { "name": "Growth", "audience": "For growing marketing teams", "badge": "Most popular",
+            "monthly": 30, "yearly": 24,
+            "features": [ { "line": "15 social accounts" }, { "line": "Approval workflows" }, { "line": "AI caption drafts" } ],
+            "ctaLabel": "Start 14-day trial", "ctaUrl": "https://app.cadence.so/signup?plan=growth" },
+          { "name": "Scale", "audience": "For agencies and brands", "priceLabel": "Let's talk",
+            "features": [ { "line": "Unlimited accounts" }, { "line": "SSO and audit log" } ],
+            "ctaLabel": "Talk to sales", "ctaUrl": "/contact-sales" }
+        ],
+        "comparison": [
+          { "group": "Usage", "feature": "Scheduled posts", "starter": "30 a month", "growth": "Unlimited", "scale": "Unlimited" },
+          { "group": "Features", "feature": "AI caption drafts", "starter": "No", "growth": "50 a month", "scale": "Yes" }
+        ],
+        "fineprint": "Prices in USD, excluding tax. Yearly plans are billed once a year."
+      } } }
+  ] } ]
+}
+```
+
+Bound template (the Growth card and one comparison row; `pricing-01` is the instance id):
+
+```html
+<section class="pricing" id="pricing" data-bcms-block="pricing-01">
+  <h2 data-bcms-field="pricing-01__overrides.heading" data-bcms-kind="text">Plans that grow with your calendar</h2>
+  <article class="plan plan--featured">
+    <span class="ribbon" data-bcms-field="pricing-01__overrides.plans[1].badge" data-bcms-kind="text">Most popular</span>
+    <h3 data-bcms-field="pricing-01__overrides.plans[1].name" data-bcms-kind="text">Growth</h3>
+    <p class="price"><span class="amount">$<span data-bcms-field="pricing-01__overrides.plans[1].yearly">24</span></span><span class="per">/mo</span></p>
+    <ul class="checks">
+      <li data-bcms-field="pricing-01__overrides.plans[1].features[0].line" data-bcms-kind="text">15 social accounts</li>
+    </ul>
+    <a class="btn btn-primary" href="https://app.cadence.so/signup?plan=growth"
+      data-bcms-props="pricing-01__overrides.plans[1].ctaUrl|url|href">
+      <span data-bcms-field="pricing-01__overrides.plans[1].ctaLabel" data-bcms-kind="text">Start 14-day trial</span></a>
+  </article>
+  <table class="compare"><tbody>
+    <tr><th scope="row" data-bcms-field="pricing-01__overrides.comparison[0].feature" data-bcms-kind="text">Scheduled posts</th>
+      <td data-bcms-field="pricing-01__overrides.comparison[0].starter" data-bcms-kind="text">30 a month</td>
+      <td data-bcms-field="pricing-01__overrides.comparison[0].growth" data-bcms-kind="text">Unlimited</td>
+      <td data-bcms-field="pricing-01__overrides.comparison[0].scale" data-bcms-kind="text">Unlimited</td></tr>
+  </tbody></table>
+</section>
+```
+
+- Use the package `bind` and `bindProps` helpers inside an instance; they produce these addresses.
+  A definition block id (`pr-heading`) is shared by every instance and binds to nothing.
+- Bind the digits, not `$24/mo`. The symbol and the period come from the template. Bind the price
+  on screen; when the switch shows monthly, the address is `.monthly`.
+- A cell the template draws as an icon ("Yes", "No") is not bound: it is edited in the side panel.
+- A comparison written as prose instead belongs in a `richtext` prop as a Portable Text `table`
+  ([portable-text.md](portable-text.md)); then the wrapper of that one value is the bound element.
+
+A typed table is available on both sides. On a component each `table` column is one sub-field
+with its own type (`number`, `boolean`, `url`, ...), as `monthly` and `ctaUrl` are above. On a
+model it is a `repeater` (stored as an `array` with `config.zones.repeatable.fields`): one field
+per column, of any field type, `minItems` / `maxItems` on the repeatable zone, and
+`ui.layout: "table"` to edit the rows as a grid. To key rows to plan ids, give the model a `text`
+column with `unique: true`. A value only a developer may change is a model field with
+`readOnly: "developer"` and a `lockReason`.
+
+Not available today: a per-cell type (a column has one type for every row), and a caption,
+footnotes or row groups as parts of the table (model them as fields beside it, as `group` and
+`fineprint` are here). Offer markup: no JSON-LD is built from prices. Paste it as `schema` on
+`update_page` when the page needs it. A fourth plan in the comparison is a new sub-field, a schema
+change.
+
+## 4. Testimonials kept as a collection
+
+Source: three quote cards on a home page. The same quotes also show on the pricing and product
+pages.
+
+```html
+<section class="testimonials bg-stone-50 py-24">
+  <p class="eyebrow">Customers</p>
+  <h2 class="text-3xl">Teams that stopped chasing spreadsheets</h2>
+  <div class="cards grid gap-6 md:grid-cols-3">
+    <figure class="t-card">
+      <div class="stars" role="img" aria-label="5 out of 5 stars">★★★★★</div>
+      <blockquote><p>&ldquo;We closed March in a day and a half. Our auditors asked what changed.&rdquo;</p></blockquote>
+      <figcaption>
+        <img class="avatar" src="/img/people/dana-ruiz.jpg" alt="" width="48" height="48">
+        <span class="name">Dana Ruiz</span><span class="role">Controller, Brightwell Foods</span>
+      </figcaption>
+    </figure>
+    <!-- Omar Haddad, VP Finance, Northgate Logistics, 5 stars; Mei Tanaka, Finance Lead, Alder Studio, 4 stars, no photo -->
+  </div>
+  <a class="btn btn-outline" href="/customers">Read all customer stories</a>
+</section>
+```
+
+Reasoning:
+
+1. Search the site before modelling rows inside the section. The quotes repeat on three pages, so
+   each quote is one entry of a content model and is written once.
+2. Per entry: the quote without the curly quotes (the template adds them), name, role and company
+   split at the comma, photo, and the rating read from `aria-label`. Add a consent switch:
+   publishing a person's words needs their permission.
+3. The avatar's `alt=""` is correct: the name sits beside it. Keep the alt text empty.
+4. The section keeps its own eyebrow, heading and button. How it gets its three quotes depends on
+   where it lives (table below).
+
+Schema (`create_content_model`), then the home page's own fields:
+
+```json
+{
+  "name": "Testimonial",
+  "slug": "testimonial",
+  "urlPattern": "/customers/:slug",
+  "fields": [
+    { "key": "quote", "label": "Quote", "type": "text", "richText": false, "required": true,
+      "helpText": "Without quotation marks; the page adds them." },
+    { "key": "name", "label": "Name", "type": "text", "richText": false, "required": true },
+    { "key": "role", "label": "Role", "type": "text", "richText": false },
+    { "key": "company", "label": "Company", "type": "text", "richText": false },
+    { "key": "photo", "label": "Photo", "type": "image" },
+    { "key": "rating", "label": "Rating", "type": "number", "config": { "min": 1, "max": 5, "step": 1 } },
+    { "key": "consent", "label": "Permission to publish", "type": "boolean" }
+  ]
+}
+```
+
+```json
+[
+  { "key": "testimonials_eyebrow", "label": "Eyebrow", "type": "text", "richText": false },
+  { "key": "testimonials_title", "label": "Heading", "type": "text", "richText": false },
+  { "key": "testimonials_picks", "label": "Testimonials", "type": "multi-reference",
+    "config": { "contentModelId": "<testimonial model id>", "min": 3, "max": 9 },
+    "helpText": "Pick 3, 6 or 9 so the grid has no gaps." },
+  { "key": "testimonials_cta", "label": "Button", "type": "button" }
+]
+```
+
+Value: entries first (`create_content_entries`, drafts, ids come back), then the page:
+
+```json
+{
+  "contentModelId": "<testimonial model id>",
+  "entries": [
+    { "slug": "dana-ruiz", "data": { "quote": "We closed March in a day and a half. Our auditors asked what changed.",
+        "name": "Dana Ruiz", "role": "Controller", "company": "Brightwell Foods",
+        "photo": { "url": "/img/people/dana-ruiz.jpg", "altText": "" }, "rating": 5, "consent": true } },
+    { "slug": "omar-haddad", "data": { "quote": "Matching used to eat two people for a week. Now it is a coffee.",
+        "name": "Omar Haddad", "role": "VP Finance", "company": "Northgate Logistics",
+        "photo": { "url": "/img/people/omar-haddad.jpg", "altText": "" }, "rating": 5, "consent": true } },
+    { "slug": "mei-tanaka", "data": { "quote": "The audit log alone paid for it.",
+        "name": "Mei Tanaka", "role": "Finance Lead", "company": "Alder Studio", "rating": 4, "consent": true } }
+  ]
+}
+```
+
+```json
+{
+  "pageId": "<home page id>",
+  "data": {
+    "testimonials_eyebrow": "Customers",
+    "testimonials_title": "Teams that stopped chasing spreadsheets",
+    "testimonials_picks": ["<dana entry id>", "<omar entry id>", "<mei entry id>"],
+    "testimonials_cta": { "label": "Read all customer stories", "href": "/customers", "variant": "outline" }
+  }
+}
+```
+
+A reference value is the entry id as a string; a multi-reference is a list of them. An id that
+does not exist is refused with a 400 ("ref_missing"), so create the entries before the page value.
+
+How a band shows the entries, by where it lives:
+
+| Where | What production supports |
+|---|---|
+| A code-built page (this example) | A `multi-reference` page field holds the picked ids; the template reads the entries and draws the cards |
+| The collection's own dynamic page (`/customers`) | A `collection` block: `cardComponentId`, `limit` (1 to 200), `order` (`newest` or `oldest`), `emptyText` |
+| A component placed on several pages | A `table` prop filled per instance. The quotes are then copies: a change to one entry is repeated by hand on each instance |
+
+Bound template (the section's own values; one card shown):
+
+```html
+<p class="eyebrow" data-bcms-field="testimonials_eyebrow" data-bcms-kind="text">Customers</p>
+<h2 class="text-3xl" data-bcms-field="testimonials_title" data-bcms-kind="text">Teams that stopped chasing spreadsheets</h2>
+<div class="cards grid gap-6 md:grid-cols-3">
+  <figure class="t-card">
+    <div class="stars" role="img" aria-label="5 out of 5 stars">★★★★★</div>
+    <blockquote><p>&ldquo;We closed March in a day and a half. Our auditors asked what changed.&rdquo;</p></blockquote>
+    <figcaption><img class="avatar" src="/img/people/dana-ruiz.jpg" alt=""><span class="name">Dana Ruiz</span></figcaption>
+  </figure>
+</div>
+```
+
+- The cards carry no page binding. Their words belong to the entries and are edited there, once,
+  for every page that shows them. The picked list is changed in the side panel.
+- Draw the stars from `rating`; never store the glyphs.
+
+One chosen entry on a hosted page is a `collection` block, not a prop: `source: { modelId }`,
+`pinnedIds: ["<entry id>"]`, `limit: 1` and `cardComponentId` naming the card that draws it. Pinned
+entries come first, so the limit keeps exactly that one.
+
+Not available today: a component prop that references entries (there is no reference prop type; it
+would save and render nothing). A listing chosen by tag or filter on a route the repo's code
+renders: the `collection` block with `source`, `filters` and `sort` is drawn by the hosted
+renderer only, so there a "latest for this product" list is a query in the site's code. A
+decorative flag on an image VALUE: an empty `altText` is the signal for one placement;
+`update_media` `decorative: true` marks the asset itself.
+
+## 5. FAQ accordion with FAQPage markup
+
+Source: a help band built from `<details>`, with hand-written FAQPage JSON-LD beside it.
+
+```html
+<section class="faq" id="faq">
+  <h2>Questions, answered</h2>
+  <p>Straight answers about billing, data and switching tools.</p>
+  <details class="faq-item" open>
+    <summary><h3>Can I cancel at any time?</h3><svg class="chevron" aria-hidden="true"/></summary>
+    <div class="faq-item__body"><p>Yes. Cancel from <strong>Settings &gt; Billing</strong> and you keep access until the end of the period.</p></div>
+  </details>
+  <details class="faq-item">
+    <summary><h3>Where is my data stored?</h3><svg class="chevron" aria-hidden="true"/></summary>
+    <div class="faq-item__body"><p>In the EU or the US, your choice at sign-up. Read the <a href="/security">security overview</a>.</p></div>
+  </details>
+  <details class="faq-item">
+    <summary><h3>How do I move from spreadsheets?</h3><svg class="chevron" aria-hidden="true"/></summary>
+    <div class="faq-item__body"><p>Most teams switch in an afternoon:</p>
+      <ol><li>Connect your bank.</li><li>Import last month's CSV.</li><li>Invite your team.</li></ol></div>
+  </details>
+  <p class="faq__more">Still stuck? <a href="/support">Talk to support</a></p>
+</section>
+<script type="application/ld+json">{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[...]}</script>
+```
+
+Reasoning:
+
+1. Repeated `<details>` with a question and an answer, specific to this page: a repeater in the
+   page's fields. Move to a collection only when the same questions repeat on several pages.
+2. The question is a plain string; the `<h3>` and the chevron belong to the template. The answer
+   carries bold text, a link and a list: rich text, narrowed to what answers use.
+3. `open` on the first item is behaviour. It stays in the template.
+4. "Talk to support" is a `button` field. "Still stuck?" is fixed template copy.
+5. Delete the hand-written `<script type="application/ld+json">` and set the page's schema type
+   instead. Name the row keys so they contain `question` and `answer`: the FAQPage builder finds
+   the first list on the page whose rows have both.
+
+Schema:
+
+```json
+[
+  { "key": "faq_title", "label": "Heading", "type": "text", "richText": false },
+  { "key": "faq_intro", "label": "Intro", "type": "text", "richText": false },
+  { "key": "faq_items", "label": "Questions", "type": "repeater",
+    "ui": { "preview": { "title": "faq_question" }, "itemLabel": "Question" },
+    "fields": [
+      { "key": "faq_question", "label": "Question", "type": "text", "richText": false, "required": true },
+      { "key": "faq_answer", "label": "Answer", "type": "richtext", "required": true,
+        "config": { "accept": ["p", "b", "i", "link", "ul", "ol"] } }
+    ] },
+  { "key": "faq_support", "label": "Support link", "type": "button" }
+]
+```
+
+Value (`set_page_content` `data`; each answer is a Portable Text array, shown below):
+
+```jsonc
+{
+  "faq_title": "Questions, answered",
+  "faq_intro": "Straight answers about billing, data and switching tools.",
+  "faq_items": { "repeatable": [
+    { "faq_question": "Can I cancel at any time?", "faq_answer": [ /* one paragraph, "Settings > Billing" marked strong */ ] },
+    { "faq_question": "Where is my data stored?", "faq_answer": [ /* array A */ ] },
+    { "faq_question": "How do I move from spreadsheets?", "faq_answer": [ /* array B */ ] }
+  ] },
+  "faq_support": { "label": "Talk to support", "href": "/support", "variant": "link" }
+}
+```
+
+Array A, a paragraph with a link:
+
+<!-- pt-example -->
+```json
+[
+  { "_type": "block", "_key": "a2p1", "style": "normal",
+    "markDefs": [{ "_type": "link", "_key": "a2l1", "href": "/security" }],
+    "children": [
+      { "_type": "span", "_key": "a2s1", "text": "In the EU or the US, your choice at sign-up. Read the ", "marks": [] },
+      { "_type": "span", "_key": "a2s2", "text": "security overview", "marks": ["a2l1"] },
+      { "_type": "span", "_key": "a2s3", "text": ".", "marks": [] }
+    ] }
+]
+```
+
+Array B, a paragraph then a flat numbered list:
+
+<!-- pt-example -->
+```json
+[
+  { "_type": "block", "_key": "a3p1", "style": "normal", "markDefs": [],
+    "children": [{ "_type": "span", "_key": "a3s1", "text": "Most teams switch in an afternoon:", "marks": [] }] },
+  { "_type": "block", "_key": "a3i1", "style": "normal", "listItem": "number", "level": 1, "markDefs": [],
+    "children": [{ "_type": "span", "_key": "a3s2", "text": "Connect your bank.", "marks": [] }] },
+  { "_type": "block", "_key": "a3i2", "style": "normal", "listItem": "number", "level": 1, "markDefs": [],
+    "children": [{ "_type": "span", "_key": "a3s3", "text": "Import last month's CSV.", "marks": [] }] },
+  { "_type": "block", "_key": "a3i3", "style": "normal", "listItem": "number", "level": 1, "markDefs": [],
+    "children": [{ "_type": "span", "_key": "a3s4", "text": "Invite your team.", "marks": [] }] }
+]
+```
+
+Structured data (`update_page`):
+
+```json
+{ "pageId": "<page id>", "schemaType": "FAQPage" }
+```
+
+Bound template (second item):
+
+```html
+<details class="faq-item">
+  <summary><h3 data-bcms-field="faq_items[1].faq_question" data-bcms-kind="text">Where is my data stored?</h3>
+    <svg class="chevron" aria-hidden="true"/></summary>
+  <div class="faq-item__body" data-bcms-field="faq_items[1].faq_answer" data-bcms-kind="richtext">
+    <p>In the EU or the US, your choice at sign-up. Read the <a href="/security">security overview</a>.</p>
+  </div>
+</details>
+```
+
+- The question binds on the `<h3>`, not the `<summary>`: a save on the summary would erase the
+  chevron.
+- `.faq-item__body` renders nothing but the answer, so it is the answer's element. If it also held
+  a "Was this helpful?" row, wrap the answer in its own `<div>` and bind that.
+- A paragraph inside an answer is addressed `faq_items[1].faq_answer#a2p1`; keep `_key` values
+  stable when you rewrite an answer, and write the whole field, never one block.
+
+Not available today: FAQPage markup that appears on its own. Without `schemaType: "FAQPage"` the
+page gets WebPage. An "open several at once" setting has no field type of its own; if editors
+need it, add a `boolean` field and have the template read it.
+
+## 9. Bento grid with per-cell sizes
+
+Source: the cookware brand's home page. The kit's `core-bento` entry is this shape, and
+`bento-feature-showcase` is its responsive long form ([kit-scenarios.md](kit-scenarios.md)).
+
+```html
+<section class="bento" id="field">
+  <p class="eyebrow">In the field</p>
+  <h2>Made to be handed down.</h2>
+  <div class="bento__grid grid grid-cols-4 gap-6">
+    <figure class="cell col-span-2 row-span-2 cell--dark">
+      <img src="/img/sierra-dawn-2400.jpg" alt="Dawn over a Sierra camp, kettle steaming" width="2400" height="2400">
+      <figcaption>Three nights in the Sierra</figcaption>
+    </figure>
+    <div class="cell cell--brand"><i class="ti ti-flame" aria-hidden="true"></i>
+      <span class="stat__value">120k+</span><span class="stat__label">Fires cooked over</span></div>
+    <div class="cell"><i class="ti ti-star" aria-hidden="true"></i>
+      <span class="stat__value">4.9</span><span class="stat__label">Average review</span></div>
+    <blockquote class="cell col-span-2"><p>Our restaurant runs four Ember ovens over live fire every night.</p>
+      <cite>Chef Amara Osei, Hearth &amp; Ash, Portland</cite></blockquote>
+  </div>
+</section>
+```
+
+Reasoning:
+
+1. The grid's children differ in shape (an image, two stats, a quote) and in size. Different
+   shapes chosen by the editor are slot children, not rows of one list.
+2. Each cell's size and surface belong to its place in this grid, not to the cell. Reading
+   `col-span-2 row-span-2` and `cell--dark` into the image tile's own props would carry a
+   meaningless span to every other page that reuses the tile. They go in the slot's settings.
+3. Size is a small set of presets (1 × 1, 2 × 1, 1 × 2, 2 × 2), so it is a select, never a free
+   column number. If the source's spans do not fit four presets, it is the per-cell grid
+   (`grid-cell-layout`), not a bento.
+4. The four-column versus three-column layout is a variant: a second component sharing the
+   `sectionType`, with the same prop keys.
+5. The icons and the gap between cells are design: they stay in the template's classes.
+
+Schema: one component per tile kind (`create_component`, then `publish_component`). The stat tile:
+
+```json
+{
+  "name": "Stat tile",
+  "slug": "stat-tile",
+  "category": "content",
+  "description": "A big number with a short label.",
+  "blockJson": [
+    { "type": "section", "id": "stat-root", "props": { "children": [
+      { "type": "text", "id": "stat-value", "props": { "html": "" } },
+      { "type": "text", "id": "stat-label", "props": { "html": "" } }
+    ] } }
+  ],
+  "props": [
+    { "key": "value", "label": "Number", "type": "text", "target": { "blockId": "stat-value", "path": "props.html" } },
+    { "key": "label", "label": "Label", "type": "text", "target": { "blockId": "stat-label", "path": "props.html" } }
+  ]
+}
+```
+
+The image tile (`image`, `caption`) and the quote tile (`quote`, `author`, `role`) are built the
+same way. Then the grid, whose `cells` slot lists them:
+
+```json
+{
+  "name": "Bento grid",
+  "slug": "bento-grid",
+  "sectionType": "bento",
+  "category": "section",
+  "description": "A mosaic of image, stat and quote cells, each with its own size and surface.",
+  "blockJson": [
+    { "type": "section", "id": "bento-root", "props": { "children": [
+      { "type": "text", "id": "bento-eyebrow", "props": { "html": "" } },
+      { "type": "heading", "id": "bento-title", "props": { "text": "", "level": 2 } },
+      { "type": "section", "id": "bento-cells", "props": { "children": [] } }
+    ] } }
+  ],
+  "props": [
+    { "key": "eyebrow", "label": "Eyebrow", "type": "text", "target": { "blockId": "bento-eyebrow", "path": "props.html" } },
+    { "key": "heading", "label": "Heading", "type": "text", "target": { "blockId": "bento-title", "path": "props.text" } },
+    { "key": "cells", "label": "Cells", "type": "slot",
+      "target": { "blockId": "bento-cells", "path": "props.children" },
+      "config": {
+        "multiple": true, "minItems": 3, "maxItems": 9,
+        "componentIds": ["<image tile id>", "<stat tile id>", "<quote tile id>"],
+        "slotSettings": [
+          { "key": "span", "label": "Size", "type": "select", "defaultValue": "1x1",
+            "options": [
+              { "value": "1x1", "label": "Small" }, { "value": "2x1", "label": "Wide" },
+              { "value": "1x2", "label": "Tall" }, { "value": "2x2", "label": "Large" } ] },
+          { "key": "tone", "label": "Surface", "type": "select", "defaultValue": "light",
+            "options": [
+              { "value": "light", "label": "Light" }, { "value": "dark", "label": "Dark" },
+              { "value": "brand", "label": "Brand" } ] }
+        ] } }
+  ]
+}
+```
+
+Value: the instance, inside the page's whole `blockJson` (`update_page` with `ifMatch`, or
+`compose_pages`). Each cell names its tile component in `_type`, holds that tile's props at its
+root, and its place in the grid in `_settings`:
+
+```json
+{ "type": "component", "id": "home-bento", "props": { "componentId": "<bento grid id>", "overrides": {
+  "eyebrow": "In the field",
+  "heading": "Made to be handed down.",
+  "cells": [
+    { "_key": "g1", "_type": "<image tile id>", "_settings": { "span": "2x2", "tone": "dark" },
+      "image": "/img/sierra-dawn-2400.jpg", "caption": "Three nights in the Sierra" },
+    { "_key": "g2", "_type": "<stat tile id>", "_settings": { "span": "1x1", "tone": "brand" },
+      "value": "120k+", "label": "Fires cooked over" },
+    { "_key": "g3", "_type": "<stat tile id>", "_settings": { "span": "1x1", "tone": "light" },
+      "value": "4.9", "label": "Average review" },
+    { "_key": "g4", "_type": "<quote tile id>", "_settings": { "span": "2x1", "tone": "light" },
+      "quote": "Our restaurant runs four Ember ovens over live fire every night.",
+      "author": "Chef Amara Osei", "role": "Hearth & Ash, Portland" }
+  ] } } }
+```
+
+Bound template: render the blocks with `BcmsBlocks`. Each cell arrives as a `component` block
+whose `props.slotSettings` holds its `_settings`; the template turns `span` and `tone` into its own
+grid and surface classes.
+
+```html
+<section data-bcms-block="home-bento">
+  <p data-bcms-field="home-bento__overrides.eyebrow" data-bcms-kind="text">In the field</p>
+  <h2 data-bcms-field="home-bento__overrides.heading" data-bcms-kind="text">Made to be handed down.</h2>
+  <div class="bento__grid grid grid-cols-4 gap-6">
+    <figure class="cell col-span-2 row-span-2 cell--dark">…</figure>
+  </div>
+</section>
+```
+
+- A `_settings` value that does not fit the slot's `slotSettings` is refused, naming the cell's
+  `_key`; a slot with no `slotSettings` takes no `_settings` at all.
+- `_key` is the cell's identity: keep it stable across reorders.
+- Publish every tile component before the grid: a draft child renders nothing.
+- A cell's copy is edited in the placement's `cells` list, not by clicking it on the canvas
+  ([components.md](components.md) §1).
+
+Not available today: spans that depend on the variant's column count (validate them yourself),
+per-breakpoint spans, and a phone order per cell.
+
+## Checks after any example
+
+1. Read back what you wrote: `get_page`, `get_component` or `get_layout`. A richtext value comes
+   back as an envelope, an image as the resolved asset, a repeater as `{ repeatable }`.
+2. `get_site_composition`: every placed component is published and no required prop is empty.
+3. After the next release, `get_binding_report` for the route: no unmatched path for the fields
+   you bound, and the mode you expect.
+4. Edit one value of each bound kind in the Visual Editor (a text, a link, an image, a body
+   block) and confirm only that element changed.
+5. Publishing needs the user's authorization. Say what is still a draft.