@bettercms-ai/mcp 0.83.0 → 0.83.2

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

@@ -1,509 +1,509 @@
----
-title: "Worked examples: entries, chrome and nested blocks"
-description: "Three more conversions from source HTML to a production schema, value and bound template: a blog post as a collection entry, a mega menu in the Global Layout, and tabs holding columns of cards."
----
-
-# Worked examples, continued: entries, chrome and nested blocks
-
-Examples 1 to 5, the table of which shape to use, and the rules every example follows are in
-[worked-examples.md](worked-examples.md). Each example here runs the same five steps: source
-markup (trimmed), reasoning, schema, value, bound template. Rules behind the shapes:
-[content-modeling.md](content-modeling.md), [components.md](components.md),
-[bindings.md](bindings.md), [portable-text.md](portable-text.md).
-
-## Contents
-
-- [6. Blog post as a collection entry](#6-blog-post-as-a-collection-entry)
-- [7. Mega menu in the Global Layout](#7-mega-menu-in-the-global-layout)
-- [8. Tabs holding columns of cards](#8-tabs-holding-columns-of-cards)
-- [Checks](#checks)
-
-## 6. Blog post as a collection entry
-
-Source: one post of many, on `/blog/why-your-month-end-close-takes-eight-days`.
-
-```html
-<article class="post" itemscope itemtype="https://schema.org/BlogPosting">
-  <header class="post__header">
-    <a class="post__topic" href="/blog/topic/finance-ops">Finance ops</a>
-    <h1 itemprop="headline">Why your month-end close takes eight days</h1>
-    <p class="post__dek">Three small problems repeat every month. Here is how to remove them.</p>
-    <div class="byline">
-      <a rel="author" href="/authors/priya-shah">Priya Shah</a>
-      <time datetime="2026-09-18T09:00:00-04:00">September 18, 2026</time> · <span>7 min read</span>
-    </div>
-  </header>
-  <figure class="post__cover">
-    <img src="/blog/close-cover.jpg" alt="A calendar with the last week of the month circled in red" width="1600" height="900">
-    <figcaption>Photo: Alder Studio</figcaption>
-  </figure>
-  <div class="post__body prose">
-    <p>Most month-end closes do not run late because of hard problems. They run late because of three small ones that repeat every month.</p>
-    <h2 id="where-the-days-go">Where the days go</h2>
-    <p>We timed 41 finance teams through a close. On average, <strong>62% of the time</strong> went to matching and chasing, not to judgement.</p>
-    <ul><li>Bank lines without a reference</li><li>Card spend with no receipt attached</li></ul>
-    <figure class="wp-block-image"><img src="/blog/close-time-chart.png" alt="Bar chart: matching takes 3.1 days, review 1.2 days, reporting 0.8 days"><figcaption>Median time per close stage, 41 teams, Q2 2026.</figcaption></figure>
-    <table class="wp-block-table"><thead><tr><th>Stage</th><th>Manual</th></tr></thead><tbody><tr><td>Matching</td><td>3.1 days</td></tr></tbody></table>
-    <figure class="wp-block-embed is-provider-youtube"><iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ" title="Ten-minute close walkthrough"></iframe></figure>
-    <blockquote class="pullquote"><p>The close got shorter the week we stopped exporting CSVs.</p></blockquote>
-    <pre><code class="language-sql">SELECT * FROM bank_lines WHERE reference IS NULL;</code></pre>
-    <p>Want the checklist we use? <a href="/resources/close-checklist">Download it here</a>.</p>
-  </div>
-  <aside class="share">...</aside>
-  <section class="related">...</section>
-</article>
-```
-
-Reasoning:
-
-1. An `<article>` with its own URL, a byline and a date, one of many: an entry of a content model
-   with one dynamic page. Never a page per post.
-2. Title, summary, cover and caption are fields. The author and the topic are entries of their
-   own models, referenced by id: find or create `/authors/priya-shah` and the topic first.
-3. The date comes from `<time datetime>`: ISO 8601 with its offset, exactly as written.
-4. "7 min read" is computed by the template from the body. Share buttons and related posts are
-   template parts. None of the three is stored.
-5. The body is the one `document` field. Headings start at `h2` (the title is the `h1`). Lists
-   become flat list blocks; the figure, the embed, the table and the code block become block
-   objects.
-6. No SEO fields and no microdata. Meta values go in the entry's `meta`; BlogPosting markup is
-   automatic for a collection with a body, a date and an author.
-
-Schema (`create_content_model`):
-
-```json
-{
-  "name": "Post",
-  "slug": "post",
-  "urlPattern": "/blog/:slug",
-  "fields": [
-    { "key": "title", "label": "Title", "type": "text", "richText": false, "required": true, "placement": "title" },
-    { "key": "excerpt", "label": "Summary", "type": "text", "richText": false, "placement": "excerpt" },
-    { "key": "cover", "label": "Cover image", "type": "image", "placement": "cover" },
-    { "key": "cover_caption", "label": "Cover caption", "type": "text", "richText": false },
-    { "key": "author", "label": "Author", "type": "reference", "required": true, "config": { "contentModelId": "<author model id>" } },
-    { "key": "topics", "label": "Topics", "type": "multi-reference", "config": { "contentModelId": "<topic model id>", "max": 3 } },
-    { "key": "date", "label": "Publish date", "type": "datetime" },
-    { "key": "body", "label": "Body", "type": "document" }
-  ]
-}
-```
-
-Then the template page: `create_page` with `pageType: "dynamic"`, and `update_page` with
-`dynamic: { "previewPath": "/blog/{slug}", "modelId": "<post model id>" }`.
-
-Value (`create_content_entry`; `body` is the Portable Text array below):
-
-```jsonc
-{
-  "contentModelId": "<post model id>",
-  "slug": "why-your-month-end-close-takes-eight-days",
-  "data": {
-    "title": "Why your month-end close takes eight days",
-    "excerpt": "Three small problems repeat every month. Here is how to remove them.",
-    "cover": { "url": "/blog/close-cover.jpg", "altText": "A calendar with the last week of the month circled in red" },
-    "cover_caption": "Photo: Alder Studio",
-    "author": "<priya-shah entry id>",
-    "topics": ["<finance-ops entry id>"],
-    "date": "2026-09-18T09:00:00-04:00",
-    "body": [ /* the array below */ ]
-  }
-}
-```
-
-<!-- pt-example -->
-```json
-[
-  { "_type": "block", "_key": "b01", "style": "normal", "markDefs": [],
-    "children": [{ "_type": "span", "_key": "b01s1", "text": "Most month-end closes do not run late because of hard problems. They run late because of three small ones that repeat every month.", "marks": [] }] },
-  { "_type": "block", "_key": "b02", "style": "h2", "markDefs": [],
-    "children": [{ "_type": "span", "_key": "b02s1", "text": "Where the days go", "marks": [] }] },
-  { "_type": "block", "_key": "b03", "style": "normal", "markDefs": [],
-    "children": [
-      { "_type": "span", "_key": "b03s1", "text": "We timed 41 finance teams through a close. On average, ", "marks": [] },
-      { "_type": "span", "_key": "b03s2", "text": "62% of the time", "marks": ["strong"] },
-      { "_type": "span", "_key": "b03s3", "text": " went to matching and chasing, not to judgement.", "marks": [] }
-    ] },
-  { "_type": "block", "_key": "b04", "style": "normal", "listItem": "bullet", "level": 1, "markDefs": [],
-    "children": [{ "_type": "span", "_key": "b04s1", "text": "Bank lines without a reference", "marks": [] }] },
-  { "_type": "block", "_key": "b05", "style": "normal", "listItem": "bullet", "level": 1, "markDefs": [],
-    "children": [{ "_type": "span", "_key": "b05s1", "text": "Card spend with no receipt attached", "marks": [] }] },
-  { "_type": "bcmsBlock", "_key": "b06", "schemaKey": "builtin:image", "schemaLabel": "Image",
-    "fields": { "src": "/blog/close-time-chart.png",
-      "alt": "Bar chart: matching takes 3.1 days, review 1.2 days, reporting 0.8 days",
-      "caption": "Median time per close stage, 41 teams, Q2 2026." } },
-  { "_type": "table", "_key": "b07", "rows": [
-    { "_key": "b07r1", "head": true, "cells": [
-      { "_key": "b07c1", "header": true, "content": [
-        { "_type": "block", "_key": "b07c1b", "style": "normal", "markDefs": [],
-          "children": [{ "_type": "span", "_key": "b07c1s", "text": "Stage", "marks": [] }] } ] },
-      { "_key": "b07c2", "header": true, "content": [
-        { "_type": "block", "_key": "b07c2b", "style": "normal", "markDefs": [],
-          "children": [{ "_type": "span", "_key": "b07c2s", "text": "Manual", "marks": [] }] } ] }
-    ] },
-    { "_key": "b07r2", "cells": [
-      { "_key": "b07c3", "content": [
-        { "_type": "block", "_key": "b07c3b", "style": "normal", "markDefs": [],
-          "children": [{ "_type": "span", "_key": "b07c3s", "text": "Matching", "marks": [] }] } ] },
-      { "_key": "b07c4", "content": [
-        { "_type": "block", "_key": "b07c4b", "style": "normal", "markDefs": [],
-          "children": [{ "_type": "span", "_key": "b07c4s", "text": "3.1 days", "marks": [] }] } ] }
-    ] }
-  ] },
-  { "_type": "bcmsBlock", "_key": "b08", "schemaKey": "builtin:video", "schemaLabel": "Video",
-    "fields": { "url": "https://www.youtube.com/embed/dQw4w9WgXcQ", "title": "Ten-minute close walkthrough" } },
-  { "_type": "block", "_key": "b09", "style": "blockquote", "markDefs": [],
-    "children": [{ "_type": "span", "_key": "b09s1", "text": "The close got shorter the week we stopped exporting CSVs.", "marks": [] }] },
-  { "_type": "bcmsCode", "_key": "b10", "language": "sql", "code": "SELECT * FROM bank_lines WHERE reference IS NULL;" },
-  { "_type": "block", "_key": "b11", "style": "normal",
-    "markDefs": [{ "_type": "link", "_key": "b11l1", "href": "/resources/close-checklist" }],
-    "children": [
-      { "_type": "span", "_key": "b11s1", "text": "Want the checklist we use? ", "marks": [] },
-      { "_type": "span", "_key": "b11s2", "text": "Download it here", "marks": ["b11l1"] },
-      { "_type": "span", "_key": "b11s3", "text": ".", "marks": [] }
-    ] }
-]
-```
-
-Bound template (the entry's field keys are the addresses):
-
-```html
-<article class="post">
-  <h1 data-bcms-field="title" data-bcms-kind="text">Why your month-end close takes eight days</h1>
-  <p class="post__dek" data-bcms-field="excerpt" data-bcms-kind="text">Three small problems repeat every month. ...</p>
-  <div class="byline">
-    <a rel="author" href="/authors/priya-shah">Priya Shah</a>
-    <time datetime="2026-09-18T09:00:00-04:00">September 18, 2026</time> · <span>7 min read</span>
-  </div>
-  <figure class="post__cover">
-    <img src="/blog/close-cover.jpg" alt="A calendar with the last week of the month circled in red"
-      data-bcms-field="cover" data-bcms-kind="image">
-    <figcaption data-bcms-field="cover_caption" data-bcms-kind="text">Photo: Alder Studio</figcaption>
-  </figure>
-  <div class="post__body prose" data-bcms-field="body" data-bcms-kind="document">
-    <p data-bcms-kind="richtext">Most month-end closes do not run late ...</p>
-    <h2 data-bcms-kind="richtext">Where the days go</h2>
-    <!-- one element per block, in order -->
-  </div>
-</article>
-```
-
-- The body wrapper is kind `document`, never `richtext`: the rich text kind would repaint the
-  whole article from plain text and lose its blocks.
-- The byline, the date and the reading time are not bound. The author is edited on the author
-  entry, the date in the side panel, and the reading time is recomputed on every render.
-- Publish the author and topic entries, then the post, then the template page.
-- For hundreds of posts, run the import as code against the Management API; keep the MCP for
-  reading state and fixing single entries.
-
-Not available today: a stored reading time or any computed field. A URL pattern with more than
-one segment variable (`/blog/:year/:slug`): the pattern takes `:slug` once. A caption on a video
-block (image blocks have one). "Related posts" by topic on a hosted template is a `collection`
-block with `source`, a filter whose value is a `{{field}}` of the post shown, and
-`excludeCurrent`; a template in the repo's code builds the list itself.
-
-## 7. Mega menu in the Global Layout
-
-Source: a developer-tools header on every page.
-
-```html
-<header class="site-header sticky top-0 z-50">
-  <nav class="nav" aria-label="Main">
-    <a class="nav__logo" href="/"><img src="/brand/relay-logo.svg" alt="Relay" width="96" height="28"></a>
-    <ul class="nav__menu">
-      <li class="has-mega">
-        <button class="nav__trigger" aria-expanded="false" aria-controls="mega-product">Product</button>
-        <div class="mega" id="mega-product" hidden>
-          <div class="mega__col">
-            <p class="mega__title">Platform</p>
-            <ul>
-              <li><a href="/product/queues"><span class="mega__label">Queues</span><span class="mega__desc">Durable jobs with retries</span></a></li>
-              <li><a href="/product/workflows"><span class="mega__label">Workflows</span><span class="badge">New</span><span class="mega__desc">Multi-step jobs with state</span></a></li>
-            </ul>
-          </div>
-          <div class="mega__col">
-            <p class="mega__title">Integrations</p>
-            <ul><li><a href="/integrations/vercel">Vercel</a></li><li><a href="/integrations/supabase">Supabase</a></li></ul>
-          </div>
-        </div>
-      </li>
-      <li><a href="/pricing">Pricing</a></li>
-    </ul>
-    <a class="nav__signin" href="https://app.relay.dev/login">Sign in</a>
-    <a class="btn btn-primary btn-sm" href="https://app.relay.dev/signup">Start for free</a>
-  </nav>
-</header>
-```
-
-Reasoning:
-
-1. The same `<header>` is on every page: chrome. It lives in the Global Layout's reserved
-   `navigation` Section, edited once. Never a page field, never a section placed on each page.
-2. Each top-level `<li>` is one menu row. A `<button aria-expanded>` opens a panel and has no
-   link; a plain `<a>` is a row with a link and no panel links.
-3. A panel is columns of links: three nested lists (menu, column, link). Store two. The column
-   title becomes a value on each link row, and the template groups links by it. Two list levels
-   is the depth chrome is proven to bind at, and it is also the cap for a component's props.
-4. `sticky`, colours and height are design and stay in the code. `aria-expanded` is behaviour.
-5. The logo, "Sign in" and the button use the Section's existing logo, link and button fields.
-   Read them with `get_layout`; add only what is missing.
-
-Schema (`update_layout`, one `add-field` command, `ifMatch` from `get_layout`):
-
-```json
-{
-  "scope": "global",
-  "ifMatch": 12,
-  "commands": [
-    { "type": "add-field", "sectionId": "navigation", "field": {
-      "id": "navigation.menus", "slug": "menus", "label": "Menus", "type": "repeater",
-      "fields": [
-        { "id": "navigation.menus.label", "slug": "label", "label": "Label", "type": "text" },
-        { "id": "navigation.menus.destination", "slug": "destination", "label": "Link", "type": "link" },
-        { "id": "navigation.menus.links", "slug": "links", "label": "Panel links", "type": "repeater",
-          "fields": [
-            { "id": "navigation.menus.links.column", "slug": "column", "label": "Column title", "type": "text" },
-            { "id": "navigation.menus.links.label", "slug": "label", "label": "Label", "type": "text" },
-            { "id": "navigation.menus.links.description", "slug": "description", "label": "Description", "type": "text" },
-            { "id": "navigation.menus.links.badge", "slug": "badge", "label": "Badge", "type": "text" },
-            { "id": "navigation.menus.links.destination", "slug": "destination", "label": "Link", "type": "link" }
-          ] }
-      ] } }
-  ]
-}
-```
-
-Value (`update_layout`). A nested value lives inside its parent, keyed by child id. Prefer
-`set-field-value` on the top-level field: `set-section-values` replaces every value of the
-Section, the logo and the button included.
-
-```json
-{
-  "scope": "global",
-  "ifMatch": 13,
-  "command": { "type": "set-field-value", "sectionId": "navigation", "fieldId": "navigation.menus", "value": [
-    { "navigation.menus.label": "Product", "navigation.menus.links": [
-      { "navigation.menus.links.column": "Platform", "navigation.menus.links.label": "Queues",
-        "navigation.menus.links.description": "Durable jobs with retries", "navigation.menus.links.destination": "/product/queues" },
-      { "navigation.menus.links.column": "Platform", "navigation.menus.links.label": "Workflows",
-        "navigation.menus.links.description": "Multi-step jobs with state", "navigation.menus.links.badge": "New",
-        "navigation.menus.links.destination": "/product/workflows" },
-      { "navigation.menus.links.column": "Integrations", "navigation.menus.links.label": "Vercel",
-        "navigation.menus.links.destination": "/integrations/vercel" },
-      { "navigation.menus.links.column": "Integrations", "navigation.menus.links.label": "Supabase",
-        "navigation.menus.links.destination": "/integrations/supabase" }
-    ] },
-    { "navigation.menus.label": "Pricing", "navigation.menus.destination": "/pricing" }
-  ] }
-}
-```
-
-Each command returns the next revision. The draft goes live with `publish_layout`; confirm with
-`get_layout` and `copy: "published"`.
-
-Bound template (the trigger and one link):
-
-```html
-<button class="nav__trigger" aria-expanded="false" aria-controls="mega-product"
-  data-bcms-layout-field="layout:navigation:navigation.menus[0].navigation.menus.label">Product</button>
-<p class="mega__title">Platform</p>
-<a href="/product/queues"
-  data-bcms-props="layout:navigation:navigation.menus[0].navigation.menus.links[0].navigation.menus.links.destination|url|href">
-  <span class="mega__label"
-    data-bcms-layout-field="layout:navigation:navigation.menus[0].navigation.menus.links[0].navigation.menus.links.label">Queues</span>
-  <span class="mega__desc"
-    data-bcms-layout-field="layout:navigation:navigation.menus[0].navigation.menus.links[0].navigation.menus.links.description">Durable jobs with retries</span>
-</a>
-```
-
-- Chrome uses `data-bcms-layout-field`, never `data-bcms-field`. A row is the field id, a
-  bracketed index, then the child's full id. Do not write these by hand: `get_conversion_brief`
-  lists every chrome path; copy each one exactly.
-- The column title is not bound: one value shows once per group but is stored on every link.
-  It is edited in the side panel.
-- The label sits in its own `<span>`; a binding on the `<a>` would erase the description.
-- A page that draws its own header gets no Layout copy on top, and a nav placed on a page as a
-  section renders nowhere. Remove page-level copies.
-
-If the header is a component placed with `add-component`: declare a `table` prop for the menus
-whose rows hold one nested `table` of links, with `column` as a text sub-field, and bind its
-inputs to these Section fields with ids read from `get_layout`. Publish the component before the
-Layout.
-
-Not available today: a mega menu in the built-in navbar, which is flat (`logo`, `links` of label
-and link, one `cta`). Three nested lists in a component prop: a `table` inside a `table` saves, a
-third level is refused. A featured card per panel fits as a group on the menu row (image, eyebrow,
-title, link), not as a list of cards. A typed link value with `rel` or "opens in a new tab" on a
-menu link.
-
-## 8. Tabs holding columns of cards
-
-Source: a product tour made in a page builder. One page uses it.
-
-```html
-<section class="tour" id="tour">
-  <p class="eyebrow">How it works</p>
-  <h2>One platform, three jobs</h2>
-  <div class="tabs" data-tabs>
-    <div role="tablist" aria-label="Use cases">
-      <button role="tab" aria-controls="panel-plan" aria-selected="true"><i class="ti ti-calendar" aria-hidden="true"></i>Plan</button>
-      <button role="tab" aria-controls="panel-publish" aria-selected="false"><i class="ti ti-send" aria-hidden="true"></i>Publish</button>
-    </div>
-    <div role="tabpanel" id="panel-plan">
-      <div class="row row--gap-md">
-        <div class="col col-md-6">
-          <div class="card card--bordered">
-            <img src="/img/tour/calendar.png" alt="Content calendar with posts across a week">
-            <span class="card__eyebrow">Calendar</span>
-            <h3 class="card__title">See every channel in one week view</h3>
-            <p>Drag posts between days. Gaps and clashes show before they go live.</p>
-            <a class="btn btn-primary" href="/product/calendar">Explore the calendar</a>
-            <a class="btn btn-link" href="https://www.youtube.com/watch?v=dQw4w9WgXcQ">Watch 2-min demo</a>
-          </div>
-        </div>
-        <div class="col col-md-6">
-          <div class="stat"><span class="stat__value">3.4x</span><span class="stat__label">more posts shipped per editor</span></div>
-        </div>
-      </div>
-    </div>
-    <div role="tabpanel" id="panel-publish" hidden>
-      <div class="row">
-        <div class="col"><div class="card"><h3 class="card__title">Approvals that do not stall</h3>
-          <p>Reviewers get one link. Nothing goes out without a yes.</p>
-          <a class="btn btn-primary" href="/product/approvals">See approvals</a></div></div>
-        <div class="col"><blockquote class="quote"><p>We cut review time in half.</p><cite>Lena Ortiz, Social Lead</cite></blockquote></div>
-      </div>
-    </div>
-  </div>
-</section>
-```
-
-Reasoning:
-
-1. Count levels where the content changes kind, not `<div>`s. `.row`, `.col` and the action
-   wrapper are layout. The real levels: section, tab, column, the thing in the column.
-2. Tabs and columns are native container blocks. A `tabs` block holds tabs of a label and child
-   blocks; a `columns` block holds a list of columns, each a list of blocks. Use them; do not
-   model tabs as a table prop.
-3. A column holds different things (a card, a stat, a quote). Each is a small component placed as
-   an instance, so its copy is click-to-edit and the card can be reused. The card's two looks
-   (plain, bordered) are one `variant` select prop, not two components.
-4. One page uses the band, so the outer shape is a `section` block, not a component.
-5. `aria-selected` only says which tab opens first: behaviour. Column widths are layout.
-
-Schema: the card component (`create_component`, then `publish_component`). The stat (`value`,
-`label`) and the quote (`quote`, `cite`) components are built the same way.
-
-```json
-{
-  "name": "Tour card",
-  "slug": "tour-card",
-  "category": "content",
-  "description": "Card with an image, a title, a short text and up to two buttons.",
-  "blockJson": [
-    { "type": "section", "id": "card-root", "props": { "children": [
-      { "type": "image", "id": "card-image", "props": { "src": "", "alt": "" } },
-      { "type": "text", "id": "card-eyebrow", "props": { "html": "" } },
-      { "type": "heading", "id": "card-title", "props": { "text": "", "level": 3 } },
-      { "type": "text", "id": "card-body", "props": { "html": "" } },
-      { "type": "button", "id": "card-primary", "props": { "text": "", "href": "" } },
-      { "type": "button", "id": "card-secondary", "props": { "text": "", "href": "", "variant": "link" } }
-    ] } }
-  ],
-  "props": [
-    { "key": "variant", "label": "Look", "type": "select", "defaultValue": "plain",
-      "config": { "options": ["plain", "bordered"] }, "target": { "blockId": "card-root", "path": "props.variant" } },
-    { "key": "image", "label": "Image", "type": "image", "target": { "blockId": "card-image", "path": "props.src" } },
-    { "key": "imageAlt", "label": "Image alt text", "type": "text", "target": { "blockId": "card-image", "path": "props.alt" } },
-    { "key": "eyebrow", "label": "Eyebrow", "type": "text", "target": { "blockId": "card-eyebrow", "path": "props.html" } },
-    { "key": "title", "label": "Title", "type": "text", "target": { "blockId": "card-title", "path": "props.text" } },
-    { "key": "body", "label": "Text", "type": "text", "target": { "blockId": "card-body", "path": "props.html" } },
-    { "key": "primaryLabel", "label": "Primary button label", "type": "text", "target": { "blockId": "card-primary", "path": "props.text" } },
-    { "key": "primaryUrl", "label": "Primary button link", "type": "url", "target": { "blockId": "card-primary", "path": "props.href" } },
-    { "key": "secondaryLabel", "label": "Secondary button label", "type": "text", "target": { "blockId": "card-secondary", "path": "props.text" } },
-    { "key": "secondaryUrl", "label": "Secondary button link", "type": "url", "target": { "blockId": "card-secondary", "path": "props.href" } }
-  ]
-}
-```
-
-Value: the section block, sent inside the page's whole `blockJson` (`update_page` with `ifMatch`,
-or `compose_pages`):
-
-```json
-{ "type": "section", "id": "tour", "label": "Product tour", "props": { "children": [
-  { "type": "text", "id": "tour-eyebrow", "props": { "html": "How it works" } },
-  { "type": "heading", "id": "tour-title", "props": { "text": "One platform, three jobs", "level": 2 } },
-  { "type": "tabs", "id": "tour-tabs", "props": { "tabs": [
-    { "id": "plan", "label": "Plan", "children": [
-      { "type": "columns", "id": "plan-cols", "props": { "gap": 24, "columns": [
-        [ { "type": "component", "id": "plan-card", "props": { "componentId": "<tour card id>", "overrides": {
-            "variant": "bordered",
-            "image": "/img/tour/calendar.png", "imageAlt": "Content calendar with posts across a week",
-            "eyebrow": "Calendar", "title": "See every channel in one week view",
-            "body": "Drag posts between days. Gaps and clashes show before they go live.",
-            "primaryLabel": "Explore the calendar", "primaryUrl": "/product/calendar",
-            "secondaryLabel": "Watch 2-min demo", "secondaryUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" } } } ],
-        [ { "type": "component", "id": "plan-stat", "props": { "componentId": "<stat id>", "overrides": {
-            "value": "3.4x", "label": "more posts shipped per editor" } } } ]
-      ] } }
-    ] },
-    { "id": "publish", "label": "Publish", "children": [
-      { "type": "columns", "id": "publish-cols", "props": { "columns": [
-        [ { "type": "component", "id": "publish-card", "props": { "componentId": "<tour card id>", "overrides": {
-            "title": "Approvals that do not stall", "body": "Reviewers get one link. Nothing goes out without a yes.",
-            "primaryLabel": "See approvals", "primaryUrl": "/product/approvals" } } } ],
-        [ { "type": "component", "id": "publish-quote", "props": { "componentId": "<quote id>", "overrides": {
-            "quote": "We cut review time in half.", "cite": "Lena Ortiz, Social Lead" } } } ]
-      ] } }
-    ] }
-  ] } }
-] } }
-```
-
-Bound template: render the blocks with `BcmsBlocks` and pass the component definitions; it emits
-the attributes. What it writes:
-
-```html
-<section data-bcms-block="tour">
-  <h2 data-bcms-field="tour-title__text" data-bcms-kind="text">One platform, three jobs</h2>
-  <button role="tab" data-bcms-field="tour-tabs__tabs[0].label" data-bcms-kind="text">Plan</button>
-  <div data-bcms-block="plan-card">
-    <h3 data-bcms-field="plan-card__overrides.title" data-bcms-kind="text">See every channel in one week view</h3>
-    <a href="/product/calendar" data-bcms-props="plan-card__overrides.primaryUrl|url|href">
-      <span data-bcms-field="plan-card__overrides.primaryLabel" data-bcms-kind="text">Explore the calendar</span></a>
-  </div>
-</section>
-```
-
-- Give every block, tab and instance a stable `id`. An id is the address; changing one orphans
-  the edits made against it.
-- A block the section owns is addressed `<blockId>__<prop>`; a value inside an instance is
-  `<instanceId>__overrides.<key>`. Two instances of the card never share an address.
-- Leave an unused prop out of `overrides` (the second card has no image and one button). The
-  definition's empty default renders nothing.
-- Without the definitions passed to the renderer, every instance draws empty: check that before
-  debugging a card.
-
-A slot can hold several children. Give the `slot` prop `config: { multiple: true }` and point its
-target at a container's child list (`props.children` on a `section`, `props.columns.<n>` on a
-`columns` block); a placement then lists the children, each a published component of this project:
-
-```json
-{ "type": "component", "id": "tour-cards", "props": { "componentId": "<card grid id>", "overrides": {
-  "cards": [
-    { "componentId": "<tour card id>", "overrides": { "title": "Plan" } },
-    { "componentId": "<stat id>", "overrides": { "value": "3.4x" }, "style": { "hideOn": ["mobile"] } }
-  ] } } }
-```
-
-A fixed layout of different blocks that the editor never reorders is still a `columns` block, as
-in the tabs above. Rules and refusal codes: [components.md](components.md).
-
-Not available today: a tab icon (a tab has a label only) and a
-"first open tab" setting. Per-column widths: columns are equal, and `gap` is a whole number of
-pixels, not a named size. Per-breakpoint sizes are not available; `style.hideOn` (`["mobile"]`, `["tablet","desktop"]`) hides a block at those breakpoints, under 768, 768-1023 and 1024 and up, as `display:none` that keeps it in the HTML; all three hides it on the page, and no published page, Markdown twin or search index carries it.
-
-## Checks
-
-Run the five checks at the end of [worked-examples.md](worked-examples.md). For chrome, also read
-`get_layout` with `copy: "published"` after `publish_layout`: the draft is never the receipt.
+---
+title: "Worked examples: entries, chrome and nested blocks"
+description: "Three more conversions from source HTML to a production schema, value and bound template: a blog post as a collection entry, a mega menu in the Global Layout, and tabs holding columns of cards."
+---
+
+# Worked examples, continued: entries, chrome and nested blocks
+
+Examples 1 to 5, the table of which shape to use, and the rules every example follows are in
+[worked-examples.md](worked-examples.md). Each example here runs the same five steps: source
+markup (trimmed), reasoning, schema, value, bound template. Rules behind the shapes:
+[content-modeling.md](content-modeling.md), [components.md](components.md),
+[bindings.md](bindings.md), [portable-text.md](portable-text.md).
+
+## Contents
+
+- [6. Blog post as a collection entry](#6-blog-post-as-a-collection-entry)
+- [7. Mega menu in the Global Layout](#7-mega-menu-in-the-global-layout)
+- [8. Tabs holding columns of cards](#8-tabs-holding-columns-of-cards)
+- [Checks](#checks)
+
+## 6. Blog post as a collection entry
+
+Source: one post of many, on `/blog/why-your-month-end-close-takes-eight-days`.
+
+```html
+<article class="post" itemscope itemtype="https://schema.org/BlogPosting">
+  <header class="post__header">
+    <a class="post__topic" href="/blog/topic/finance-ops">Finance ops</a>
+    <h1 itemprop="headline">Why your month-end close takes eight days</h1>
+    <p class="post__dek">Three small problems repeat every month. Here is how to remove them.</p>
+    <div class="byline">
+      <a rel="author" href="/authors/priya-shah">Priya Shah</a>
+      <time datetime="2026-09-18T09:00:00-04:00">September 18, 2026</time> · <span>7 min read</span>
+    </div>
+  </header>
+  <figure class="post__cover">
+    <img src="/blog/close-cover.jpg" alt="A calendar with the last week of the month circled in red" width="1600" height="900">
+    <figcaption>Photo: Alder Studio</figcaption>
+  </figure>
+  <div class="post__body prose">
+    <p>Most month-end closes do not run late because of hard problems. They run late because of three small ones that repeat every month.</p>
+    <h2 id="where-the-days-go">Where the days go</h2>
+    <p>We timed 41 finance teams through a close. On average, <strong>62% of the time</strong> went to matching and chasing, not to judgement.</p>
+    <ul><li>Bank lines without a reference</li><li>Card spend with no receipt attached</li></ul>
+    <figure class="wp-block-image"><img src="/blog/close-time-chart.png" alt="Bar chart: matching takes 3.1 days, review 1.2 days, reporting 0.8 days"><figcaption>Median time per close stage, 41 teams, Q2 2026.</figcaption></figure>
+    <table class="wp-block-table"><thead><tr><th>Stage</th><th>Manual</th></tr></thead><tbody><tr><td>Matching</td><td>3.1 days</td></tr></tbody></table>
+    <figure class="wp-block-embed is-provider-youtube"><iframe src="https://www.youtube.com/embed/dQw4w9WgXcQ" title="Ten-minute close walkthrough"></iframe></figure>
+    <blockquote class="pullquote"><p>The close got shorter the week we stopped exporting CSVs.</p></blockquote>
+    <pre><code class="language-sql">SELECT * FROM bank_lines WHERE reference IS NULL;</code></pre>
+    <p>Want the checklist we use? <a href="/resources/close-checklist">Download it here</a>.</p>
+  </div>
+  <aside class="share">...</aside>
+  <section class="related">...</section>
+</article>
+```
+
+Reasoning:
+
+1. An `<article>` with its own URL, a byline and a date, one of many: an entry of a content model
+   with one dynamic page. Never a page per post.
+2. Title, summary, cover and caption are fields. The author and the topic are entries of their
+   own models, referenced by id: find or create `/authors/priya-shah` and the topic first.
+3. The date comes from `<time datetime>`: ISO 8601 with its offset, exactly as written.
+4. "7 min read" is computed by the template from the body. Share buttons and related posts are
+   template parts. None of the three is stored.
+5. The body is the one `document` field. Headings start at `h2` (the title is the `h1`). Lists
+   become flat list blocks; the figure, the embed, the table and the code block become block
+   objects.
+6. No SEO fields and no microdata. Meta values go in the entry's `meta`; BlogPosting markup is
+   automatic for a collection with a body, a date and an author.
+
+Schema (`create_content_model`):
+
+```json
+{
+  "name": "Post",
+  "slug": "post",
+  "urlPattern": "/blog/:slug",
+  "fields": [
+    { "key": "title", "label": "Title", "type": "text", "richText": false, "required": true, "placement": "title" },
+    { "key": "excerpt", "label": "Summary", "type": "text", "richText": false, "placement": "excerpt" },
+    { "key": "cover", "label": "Cover image", "type": "image", "placement": "cover" },
+    { "key": "cover_caption", "label": "Cover caption", "type": "text", "richText": false },
+    { "key": "author", "label": "Author", "type": "reference", "required": true, "config": { "contentModelId": "<author model id>" } },
+    { "key": "topics", "label": "Topics", "type": "multi-reference", "config": { "contentModelId": "<topic model id>", "max": 3 } },
+    { "key": "date", "label": "Publish date", "type": "datetime" },
+    { "key": "body", "label": "Body", "type": "document" }
+  ]
+}
+```
+
+Then the template page: `create_page` with `pageType: "dynamic"`, and `update_page` with
+`dynamic: { "previewPath": "/blog/{slug}", "modelId": "<post model id>" }`.
+
+Value (`create_content_entry`; `body` is the Portable Text array below):
+
+```jsonc
+{
+  "contentModelId": "<post model id>",
+  "slug": "why-your-month-end-close-takes-eight-days",
+  "data": {
+    "title": "Why your month-end close takes eight days",
+    "excerpt": "Three small problems repeat every month. Here is how to remove them.",
+    "cover": { "url": "/blog/close-cover.jpg", "altText": "A calendar with the last week of the month circled in red" },
+    "cover_caption": "Photo: Alder Studio",
+    "author": "<priya-shah entry id>",
+    "topics": ["<finance-ops entry id>"],
+    "date": "2026-09-18T09:00:00-04:00",
+    "body": [ /* the array below */ ]
+  }
+}
+```
+
+<!-- pt-example -->
+```json
+[
+  { "_type": "block", "_key": "b01", "style": "normal", "markDefs": [],
+    "children": [{ "_type": "span", "_key": "b01s1", "text": "Most month-end closes do not run late because of hard problems. They run late because of three small ones that repeat every month.", "marks": [] }] },
+  { "_type": "block", "_key": "b02", "style": "h2", "markDefs": [],
+    "children": [{ "_type": "span", "_key": "b02s1", "text": "Where the days go", "marks": [] }] },
+  { "_type": "block", "_key": "b03", "style": "normal", "markDefs": [],
+    "children": [
+      { "_type": "span", "_key": "b03s1", "text": "We timed 41 finance teams through a close. On average, ", "marks": [] },
+      { "_type": "span", "_key": "b03s2", "text": "62% of the time", "marks": ["strong"] },
+      { "_type": "span", "_key": "b03s3", "text": " went to matching and chasing, not to judgement.", "marks": [] }
+    ] },
+  { "_type": "block", "_key": "b04", "style": "normal", "listItem": "bullet", "level": 1, "markDefs": [],
+    "children": [{ "_type": "span", "_key": "b04s1", "text": "Bank lines without a reference", "marks": [] }] },
+  { "_type": "block", "_key": "b05", "style": "normal", "listItem": "bullet", "level": 1, "markDefs": [],
+    "children": [{ "_type": "span", "_key": "b05s1", "text": "Card spend with no receipt attached", "marks": [] }] },
+  { "_type": "bcmsBlock", "_key": "b06", "schemaKey": "builtin:image", "schemaLabel": "Image",
+    "fields": { "src": "/blog/close-time-chart.png",
+      "alt": "Bar chart: matching takes 3.1 days, review 1.2 days, reporting 0.8 days",
+      "caption": "Median time per close stage, 41 teams, Q2 2026." } },
+  { "_type": "table", "_key": "b07", "rows": [
+    { "_key": "b07r1", "head": true, "cells": [
+      { "_key": "b07c1", "header": true, "content": [
+        { "_type": "block", "_key": "b07c1b", "style": "normal", "markDefs": [],
+          "children": [{ "_type": "span", "_key": "b07c1s", "text": "Stage", "marks": [] }] } ] },
+      { "_key": "b07c2", "header": true, "content": [
+        { "_type": "block", "_key": "b07c2b", "style": "normal", "markDefs": [],
+          "children": [{ "_type": "span", "_key": "b07c2s", "text": "Manual", "marks": [] }] } ] }
+    ] },
+    { "_key": "b07r2", "cells": [
+      { "_key": "b07c3", "content": [
+        { "_type": "block", "_key": "b07c3b", "style": "normal", "markDefs": [],
+          "children": [{ "_type": "span", "_key": "b07c3s", "text": "Matching", "marks": [] }] } ] },
+      { "_key": "b07c4", "content": [
+        { "_type": "block", "_key": "b07c4b", "style": "normal", "markDefs": [],
+          "children": [{ "_type": "span", "_key": "b07c4s", "text": "3.1 days", "marks": [] }] } ] }
+    ] }
+  ] },
+  { "_type": "bcmsBlock", "_key": "b08", "schemaKey": "builtin:video", "schemaLabel": "Video",
+    "fields": { "url": "https://www.youtube.com/embed/dQw4w9WgXcQ", "title": "Ten-minute close walkthrough" } },
+  { "_type": "block", "_key": "b09", "style": "blockquote", "markDefs": [],
+    "children": [{ "_type": "span", "_key": "b09s1", "text": "The close got shorter the week we stopped exporting CSVs.", "marks": [] }] },
+  { "_type": "bcmsCode", "_key": "b10", "language": "sql", "code": "SELECT * FROM bank_lines WHERE reference IS NULL;" },
+  { "_type": "block", "_key": "b11", "style": "normal",
+    "markDefs": [{ "_type": "link", "_key": "b11l1", "href": "/resources/close-checklist" }],
+    "children": [
+      { "_type": "span", "_key": "b11s1", "text": "Want the checklist we use? ", "marks": [] },
+      { "_type": "span", "_key": "b11s2", "text": "Download it here", "marks": ["b11l1"] },
+      { "_type": "span", "_key": "b11s3", "text": ".", "marks": [] }
+    ] }
+]
+```
+
+Bound template (the entry's field keys are the addresses):
+
+```html
+<article class="post">
+  <h1 data-bcms-field="title" data-bcms-kind="text">Why your month-end close takes eight days</h1>
+  <p class="post__dek" data-bcms-field="excerpt" data-bcms-kind="text">Three small problems repeat every month. ...</p>
+  <div class="byline">
+    <a rel="author" href="/authors/priya-shah">Priya Shah</a>
+    <time datetime="2026-09-18T09:00:00-04:00">September 18, 2026</time> · <span>7 min read</span>
+  </div>
+  <figure class="post__cover">
+    <img src="/blog/close-cover.jpg" alt="A calendar with the last week of the month circled in red"
+      data-bcms-field="cover" data-bcms-kind="image">
+    <figcaption data-bcms-field="cover_caption" data-bcms-kind="text">Photo: Alder Studio</figcaption>
+  </figure>
+  <div class="post__body prose" data-bcms-field="body" data-bcms-kind="document">
+    <p data-bcms-kind="richtext">Most month-end closes do not run late ...</p>
+    <h2 data-bcms-kind="richtext">Where the days go</h2>
+    <!-- one element per block, in order -->
+  </div>
+</article>
+```
+
+- The body wrapper is kind `document`, never `richtext`: the rich text kind would repaint the
+  whole article from plain text and lose its blocks.
+- The byline, the date and the reading time are not bound. The author is edited on the author
+  entry, the date in the side panel, and the reading time is recomputed on every render.
+- Publish the author and topic entries, then the post, then the template page.
+- For hundreds of posts, run the import as code against the Management API; keep the MCP for
+  reading state and fixing single entries.
+
+Not available today: a stored reading time or any computed field. A URL pattern with more than
+one segment variable (`/blog/:year/:slug`): the pattern takes `:slug` once. A caption on a video
+block (image blocks have one). "Related posts" by topic on a hosted template is a `collection`
+block with `source`, a filter whose value is a `{{field}}` of the post shown, and
+`excludeCurrent`; a template in the repo's code builds the list itself.
+
+## 7. Mega menu in the Global Layout
+
+Source: a developer-tools header on every page.
+
+```html
+<header class="site-header sticky top-0 z-50">
+  <nav class="nav" aria-label="Main">
+    <a class="nav__logo" href="/"><img src="/brand/relay-logo.svg" alt="Relay" width="96" height="28"></a>
+    <ul class="nav__menu">
+      <li class="has-mega">
+        <button class="nav__trigger" aria-expanded="false" aria-controls="mega-product">Product</button>
+        <div class="mega" id="mega-product" hidden>
+          <div class="mega__col">
+            <p class="mega__title">Platform</p>
+            <ul>
+              <li><a href="/product/queues"><span class="mega__label">Queues</span><span class="mega__desc">Durable jobs with retries</span></a></li>
+              <li><a href="/product/workflows"><span class="mega__label">Workflows</span><span class="badge">New</span><span class="mega__desc">Multi-step jobs with state</span></a></li>
+            </ul>
+          </div>
+          <div class="mega__col">
+            <p class="mega__title">Integrations</p>
+            <ul><li><a href="/integrations/vercel">Vercel</a></li><li><a href="/integrations/supabase">Supabase</a></li></ul>
+          </div>
+        </div>
+      </li>
+      <li><a href="/pricing">Pricing</a></li>
+    </ul>
+    <a class="nav__signin" href="https://app.relay.dev/login">Sign in</a>
+    <a class="btn btn-primary btn-sm" href="https://app.relay.dev/signup">Start for free</a>
+  </nav>
+</header>
+```
+
+Reasoning:
+
+1. The same `<header>` is on every page: chrome. It lives in the Global Layout's reserved
+   `navigation` Section, edited once. Never a page field, never a section placed on each page.
+2. Each top-level `<li>` is one menu row. A `<button aria-expanded>` opens a panel and has no
+   link; a plain `<a>` is a row with a link and no panel links.
+3. A panel is columns of links: three nested lists (menu, column, link). Store two. The column
+   title becomes a value on each link row, and the template groups links by it. Two list levels
+   is the depth chrome is proven to bind at, and it is also the cap for a component's props.
+4. `sticky`, colours and height are design and stay in the code. `aria-expanded` is behaviour.
+5. The logo, "Sign in" and the button use the Section's existing logo, link and button fields.
+   Read them with `get_layout`; add only what is missing.
+
+Schema (`update_layout`, one `add-field` command, `ifMatch` from `get_layout`):
+
+```json
+{
+  "scope": "global",
+  "ifMatch": 12,
+  "commands": [
+    { "type": "add-field", "sectionId": "navigation", "field": {
+      "id": "navigation.menus", "slug": "menus", "label": "Menus", "type": "repeater",
+      "fields": [
+        { "id": "navigation.menus.label", "slug": "label", "label": "Label", "type": "text" },
+        { "id": "navigation.menus.destination", "slug": "destination", "label": "Link", "type": "link" },
+        { "id": "navigation.menus.links", "slug": "links", "label": "Panel links", "type": "repeater",
+          "fields": [
+            { "id": "navigation.menus.links.column", "slug": "column", "label": "Column title", "type": "text" },
+            { "id": "navigation.menus.links.label", "slug": "label", "label": "Label", "type": "text" },
+            { "id": "navigation.menus.links.description", "slug": "description", "label": "Description", "type": "text" },
+            { "id": "navigation.menus.links.badge", "slug": "badge", "label": "Badge", "type": "text" },
+            { "id": "navigation.menus.links.destination", "slug": "destination", "label": "Link", "type": "link" }
+          ] }
+      ] } }
+  ]
+}
+```
+
+Value (`update_layout`). A nested value lives inside its parent, keyed by child id. Prefer
+`set-field-value` on the top-level field: `set-section-values` replaces every value of the
+Section, the logo and the button included.
+
+```json
+{
+  "scope": "global",
+  "ifMatch": 13,
+  "command": { "type": "set-field-value", "sectionId": "navigation", "fieldId": "navigation.menus", "value": [
+    { "navigation.menus.label": "Product", "navigation.menus.links": [
+      { "navigation.menus.links.column": "Platform", "navigation.menus.links.label": "Queues",
+        "navigation.menus.links.description": "Durable jobs with retries", "navigation.menus.links.destination": "/product/queues" },
+      { "navigation.menus.links.column": "Platform", "navigation.menus.links.label": "Workflows",
+        "navigation.menus.links.description": "Multi-step jobs with state", "navigation.menus.links.badge": "New",
+        "navigation.menus.links.destination": "/product/workflows" },
+      { "navigation.menus.links.column": "Integrations", "navigation.menus.links.label": "Vercel",
+        "navigation.menus.links.destination": "/integrations/vercel" },
+      { "navigation.menus.links.column": "Integrations", "navigation.menus.links.label": "Supabase",
+        "navigation.menus.links.destination": "/integrations/supabase" }
+    ] },
+    { "navigation.menus.label": "Pricing", "navigation.menus.destination": "/pricing" }
+  ] }
+}
+```
+
+Each command returns the next revision. The draft goes live with `publish_layout`; confirm with
+`get_layout` and `copy: "published"`.
+
+Bound template (the trigger and one link):
+
+```html
+<button class="nav__trigger" aria-expanded="false" aria-controls="mega-product"
+  data-bcms-layout-field="layout:navigation:navigation.menus[0].navigation.menus.label">Product</button>
+<p class="mega__title">Platform</p>
+<a href="/product/queues"
+  data-bcms-props="layout:navigation:navigation.menus[0].navigation.menus.links[0].navigation.menus.links.destination|url|href">
+  <span class="mega__label"
+    data-bcms-layout-field="layout:navigation:navigation.menus[0].navigation.menus.links[0].navigation.menus.links.label">Queues</span>
+  <span class="mega__desc"
+    data-bcms-layout-field="layout:navigation:navigation.menus[0].navigation.menus.links[0].navigation.menus.links.description">Durable jobs with retries</span>
+</a>
+```
+
+- Chrome uses `data-bcms-layout-field`, never `data-bcms-field`. A row is the field id, a
+  bracketed index, then the child's full id. Do not write these by hand: `get_conversion_brief`
+  lists every chrome path; copy each one exactly.
+- The column title is not bound: one value shows once per group but is stored on every link.
+  It is edited in the side panel.
+- The label sits in its own `<span>`; a binding on the `<a>` would erase the description.
+- A page that draws its own header gets no Layout copy on top, and a nav placed on a page as a
+  section renders nowhere. Remove page-level copies.
+
+If the header is a component placed with `add-component`: declare a `table` prop for the menus
+whose rows hold one nested `table` of links, with `column` as a text sub-field, and bind its
+inputs to these Section fields with ids read from `get_layout`. Publish the component before the
+Layout.
+
+Not available today: a mega menu in the built-in navbar, which is flat (`logo`, `links` of label
+and link, one `cta`). Three nested lists in a component prop: a `table` inside a `table` saves, a
+third level is refused. A featured card per panel fits as a group on the menu row (image, eyebrow,
+title, link), not as a list of cards. A typed link value with `rel` or "opens in a new tab" on a
+menu link.
+
+## 8. Tabs holding columns of cards
+
+Source: a product tour made in a page builder. One page uses it.
+
+```html
+<section class="tour" id="tour">
+  <p class="eyebrow">How it works</p>
+  <h2>One platform, three jobs</h2>
+  <div class="tabs" data-tabs>
+    <div role="tablist" aria-label="Use cases">
+      <button role="tab" aria-controls="panel-plan" aria-selected="true"><i class="ti ti-calendar" aria-hidden="true"></i>Plan</button>
+      <button role="tab" aria-controls="panel-publish" aria-selected="false"><i class="ti ti-send" aria-hidden="true"></i>Publish</button>
+    </div>
+    <div role="tabpanel" id="panel-plan">
+      <div class="row row--gap-md">
+        <div class="col col-md-6">
+          <div class="card card--bordered">
+            <img src="/img/tour/calendar.png" alt="Content calendar with posts across a week">
+            <span class="card__eyebrow">Calendar</span>
+            <h3 class="card__title">See every channel in one week view</h3>
+            <p>Drag posts between days. Gaps and clashes show before they go live.</p>
+            <a class="btn btn-primary" href="/product/calendar">Explore the calendar</a>
+            <a class="btn btn-link" href="https://www.youtube.com/watch?v=dQw4w9WgXcQ">Watch 2-min demo</a>
+          </div>
+        </div>
+        <div class="col col-md-6">
+          <div class="stat"><span class="stat__value">3.4x</span><span class="stat__label">more posts shipped per editor</span></div>
+        </div>
+      </div>
+    </div>
+    <div role="tabpanel" id="panel-publish" hidden>
+      <div class="row">
+        <div class="col"><div class="card"><h3 class="card__title">Approvals that do not stall</h3>
+          <p>Reviewers get one link. Nothing goes out without a yes.</p>
+          <a class="btn btn-primary" href="/product/approvals">See approvals</a></div></div>
+        <div class="col"><blockquote class="quote"><p>We cut review time in half.</p><cite>Lena Ortiz, Social Lead</cite></blockquote></div>
+      </div>
+    </div>
+  </div>
+</section>
+```
+
+Reasoning:
+
+1. Count levels where the content changes kind, not `<div>`s. `.row`, `.col` and the action
+   wrapper are layout. The real levels: section, tab, column, the thing in the column.
+2. Tabs and columns are native container blocks. A `tabs` block holds tabs of a label and child
+   blocks; a `columns` block holds a list of columns, each a list of blocks. Use them; do not
+   model tabs as a table prop.
+3. A column holds different things (a card, a stat, a quote). Each is a small component placed as
+   an instance, so its copy is click-to-edit and the card can be reused. The card's two looks
+   (plain, bordered) are one `variant` select prop, not two components.
+4. One page uses the band, so the outer shape is a `section` block, not a component.
+5. `aria-selected` only says which tab opens first: behaviour. Column widths are layout.
+
+Schema: the card component (`create_component`, then `publish_component`). The stat (`value`,
+`label`) and the quote (`quote`, `cite`) components are built the same way.
+
+```json
+{
+  "name": "Tour card",
+  "slug": "tour-card",
+  "category": "content",
+  "description": "Card with an image, a title, a short text and up to two buttons.",
+  "blockJson": [
+    { "type": "section", "id": "card-root", "props": { "children": [
+      { "type": "image", "id": "card-image", "props": { "src": "", "alt": "" } },
+      { "type": "text", "id": "card-eyebrow", "props": { "html": "" } },
+      { "type": "heading", "id": "card-title", "props": { "text": "", "level": 3 } },
+      { "type": "text", "id": "card-body", "props": { "html": "" } },
+      { "type": "button", "id": "card-primary", "props": { "text": "", "href": "" } },
+      { "type": "button", "id": "card-secondary", "props": { "text": "", "href": "", "variant": "link" } }
+    ] } }
+  ],
+  "props": [
+    { "key": "variant", "label": "Look", "type": "select", "defaultValue": "plain",
+      "config": { "options": ["plain", "bordered"] }, "target": { "blockId": "card-root", "path": "props.variant" } },
+    { "key": "image", "label": "Image", "type": "image", "target": { "blockId": "card-image", "path": "props.src" } },
+    { "key": "imageAlt", "label": "Image alt text", "type": "text", "target": { "blockId": "card-image", "path": "props.alt" } },
+    { "key": "eyebrow", "label": "Eyebrow", "type": "text", "target": { "blockId": "card-eyebrow", "path": "props.html" } },
+    { "key": "title", "label": "Title", "type": "text", "target": { "blockId": "card-title", "path": "props.text" } },
+    { "key": "body", "label": "Text", "type": "text", "target": { "blockId": "card-body", "path": "props.html" } },
+    { "key": "primaryLabel", "label": "Primary button label", "type": "text", "target": { "blockId": "card-primary", "path": "props.text" } },
+    { "key": "primaryUrl", "label": "Primary button link", "type": "url", "target": { "blockId": "card-primary", "path": "props.href" } },
+    { "key": "secondaryLabel", "label": "Secondary button label", "type": "text", "target": { "blockId": "card-secondary", "path": "props.text" } },
+    { "key": "secondaryUrl", "label": "Secondary button link", "type": "url", "target": { "blockId": "card-secondary", "path": "props.href" } }
+  ]
+}
+```
+
+Value: the section block, sent inside the page's whole `blockJson` (`update_page` with `ifMatch`,
+or `compose_pages`):
+
+```json
+{ "type": "section", "id": "tour", "label": "Product tour", "props": { "children": [
+  { "type": "text", "id": "tour-eyebrow", "props": { "html": "How it works" } },
+  { "type": "heading", "id": "tour-title", "props": { "text": "One platform, three jobs", "level": 2 } },
+  { "type": "tabs", "id": "tour-tabs", "props": { "tabs": [
+    { "id": "plan", "label": "Plan", "children": [
+      { "type": "columns", "id": "plan-cols", "props": { "gap": 24, "columns": [
+        [ { "type": "component", "id": "plan-card", "props": { "componentId": "<tour card id>", "overrides": {
+            "variant": "bordered",
+            "image": "/img/tour/calendar.png", "imageAlt": "Content calendar with posts across a week",
+            "eyebrow": "Calendar", "title": "See every channel in one week view",
+            "body": "Drag posts between days. Gaps and clashes show before they go live.",
+            "primaryLabel": "Explore the calendar", "primaryUrl": "/product/calendar",
+            "secondaryLabel": "Watch 2-min demo", "secondaryUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" } } } ],
+        [ { "type": "component", "id": "plan-stat", "props": { "componentId": "<stat id>", "overrides": {
+            "value": "3.4x", "label": "more posts shipped per editor" } } } ]
+      ] } }
+    ] },
+    { "id": "publish", "label": "Publish", "children": [
+      { "type": "columns", "id": "publish-cols", "props": { "columns": [
+        [ { "type": "component", "id": "publish-card", "props": { "componentId": "<tour card id>", "overrides": {
+            "title": "Approvals that do not stall", "body": "Reviewers get one link. Nothing goes out without a yes.",
+            "primaryLabel": "See approvals", "primaryUrl": "/product/approvals" } } } ],
+        [ { "type": "component", "id": "publish-quote", "props": { "componentId": "<quote id>", "overrides": {
+            "quote": "We cut review time in half.", "cite": "Lena Ortiz, Social Lead" } } } ]
+      ] } }
+    ] }
+  ] } }
+] } }
+```
+
+Bound template: render the blocks with `BcmsBlocks` and pass the component definitions; it emits
+the attributes. What it writes:
+
+```html
+<section data-bcms-block="tour">
+  <h2 data-bcms-field="tour-title__text" data-bcms-kind="text">One platform, three jobs</h2>
+  <button role="tab" data-bcms-field="tour-tabs__tabs[0].label" data-bcms-kind="text">Plan</button>
+  <div data-bcms-block="plan-card">
+    <h3 data-bcms-field="plan-card__overrides.title" data-bcms-kind="text">See every channel in one week view</h3>
+    <a href="/product/calendar" data-bcms-props="plan-card__overrides.primaryUrl|url|href">
+      <span data-bcms-field="plan-card__overrides.primaryLabel" data-bcms-kind="text">Explore the calendar</span></a>
+  </div>
+</section>
+```
+
+- Give every block, tab and instance a stable `id`. An id is the address; changing one orphans
+  the edits made against it.
+- A block the section owns is addressed `<blockId>__<prop>`; a value inside an instance is
+  `<instanceId>__overrides.<key>`. Two instances of the card never share an address.
+- Leave an unused prop out of `overrides` (the second card has no image and one button). The
+  definition's empty default renders nothing.
+- Without the definitions passed to the renderer, every instance draws empty: check that before
+  debugging a card.
+
+A slot can hold several children. Give the `slot` prop `config: { multiple: true }` and point its
+target at a container's child list (`props.children` on a `section`, `props.columns.<n>` on a
+`columns` block); a placement then lists the children, each a published component of this project:
+
+```json
+{ "type": "component", "id": "tour-cards", "props": { "componentId": "<card grid id>", "overrides": {
+  "cards": [
+    { "componentId": "<tour card id>", "overrides": { "title": "Plan" } },
+    { "componentId": "<stat id>", "overrides": { "value": "3.4x" }, "style": { "hideOn": ["mobile"] } }
+  ] } } }
+```
+
+A fixed layout of different blocks that the editor never reorders is still a `columns` block, as
+in the tabs above. Rules and refusal codes: [components.md](components.md).
+
+Not available today: a tab icon (a tab has a label only) and a
+"first open tab" setting. Per-column widths: columns are equal, and `gap` is a whole number of
+pixels, not a named size. Per-breakpoint sizes are not available; `style.hideOn` (`["mobile"]`, `["tablet","desktop"]`) hides a block at those breakpoints, under 768, 768-1023 and 1024 and up, as `display:none` that keeps it in the HTML; all three hides it on the page, and no published page, Markdown twin or search index carries it.
+
+## Checks
+
+Run the five checks at the end of [worked-examples.md](worked-examples.md). For chrome, also read
+`get_layout` with `copy: "published"` after `publish_layout`: the draft is never the receipt.