@bettercms-ai/mcp 0.68.2 → 0.69.0

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

@@ -0,0 +1,725 @@
+---
+title: "Worked examples"
+description: "Five 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."
+---
+
+# 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)
+- [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) |
+
+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 } },
+  { "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", "variant": "primary", "arrow": true },
+    "hero_secondary": { "label": "Start free trial", "href": "https://app.kestrelfreight.com/signup", "variant": "secondary" },
+    "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`.
+- 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.
+
+Not available today: an `icon` FIELD type with a picker over a named icon set. In a model or
+page field a sprite icon is a plain name; only an inline SVG stored as an `image` with
+`media: "icon"` gets the editor's icon picker. A component prop does have the `icon` type: a
+BetterCMS icon name or an image ([components.md](components.md) §1).
+
+## 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.
+
+Not available today: typed table columns (money, boolean) and a per-cell type; every cell is text
+or one sub-field type for the whole column. Rows keyed to plan ids, and a field only a developer
+can change. 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.
+
+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.
+
+## 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.