@bettercms-ai/mcp 0.83.0 → 0.83.2

package/dist/skills/bettercms/references/kit-scenarios.md

@@ -1,712 +1,712 @@
----
-title: "Kit scenarios"
-description: "Which component-kit entry fits a section and what to do for it: all 14 kit categories and all 20 edge tags, each with when to pick it, the field shape, the pitfalls and real kit entry ids, plus what a stored component cannot carry."
----
-
-# Kit scenarios: pick the closest kit entry, then model it
-
-The component kit is 149 worked section patterns (142 kit entries in 14 categories, plus 7 core
-examples). Each entry carries notes written for a converting agent: what the section is, the HTML
-that gives it away, the mapping to fields, and the mistakes to avoid. The full list is the MCP
-resource `bettercms://kit` (an index: categories, tags and one line per entry, each with the URI
-of its category and of the entry itself) and the generated reference
-[kit-catalog.md](kit-catalog.md). This file is the hand-written chooser that points into it.
-
-## Contents
-
-- [How to use the kit](#how-to-use-the-kit)
-- [What a stored component cannot carry](#what-a-stored-component-cannot-carry)
-- [Categories](#categories)
-- [Edge tags](#edge-tags)
-- [Gaps the kit names](#gaps-the-kit-names)
-
-## How to use the kit
-
-1. **Name the band's category** from the chooser below (or detection.md §7). The category decides
-   where the section lives: chrome goes in the Global Layout, a record type becomes a collection,
-   everything else is a section component or page fields.
-2. **Pick the closest entry.** Inside the category, match the strongest HTML signal; the chooser
-   lists what separates each entry from its neighbours. Then read that entry's own resource from
-   the index: its `mcp` note is the mapping, its `pitfalls` are the review list, its `htmlSignals`
-   are what to look for, and its `component` is the props list the kit converts to (step 4).
-3. **Check its edge tags** against the [edge tag rules](#edge-tags). A band that matches no entry
-   still has tags (a list of cards is `repeater`; a price is `commerce`), and the tag rules hold
-   for it.
-4. **Never send an entry's props to `create_component` as they are.** The catalogue's props have
-   no `target`; every prop you declare needs one, aimed at the leaf your own `blockJson` renders
-   for it (schema playbook §3, [components.md](components.md) §1). Write the `blockJson` first.
-5. **Copy the shape, never the sample copy.** The entries use a fictional cookware brand
-   (Ember, Hearth & Ash, Sierra camp). Write the customer's words.
-6. **Respect the entry's limits.** A pitfall that starts "SCHEMA GAP" is something the platform
-   cannot check; do the check yourself at import time and flag what you cannot.
-
-## What a stored component cannot carry
-
-Each catalogue entry lists `notCarried`: kit features the stored component drops. Do the
-production equivalent instead of losing the intent.
-
-| notCarried | What to do instead |
-|---|---|
-| `variants` | Each layout variant is its own component sharing one `sectionType`, same prop keys ([components.md](components.md)) |
-| `kind:global` | The section is chrome: the Global Layout (`get_layout`, `update_layout`), never a page section |
-| `kind:entry (props)` | The entry is a record: a collection model and entries, not a component |
-| `slot allow` | Name the allowed child components with the slot prop's `config.componentIds` |
-| `reference target` | Point the reference at a collection with `config.contentModelId` |
-| `ai`, `category`, `item openMode`, `item settings`, `group (nested)`, `fieldset (derived)`, `document preview path`, `segmented>4`, `validation.items`, `itemNoun (derived)` | Editor presentation only; arrange the dock with [editor-chrome.md](editor-chrome.md) where it matters |
-
-## Categories
-
-Each category: when it applies, the shape, the traps, and a chooser of every entry in it.
-
-### Navigation & chrome
-
-**When:** the band is the same on every page (header, footer, announcement bar, cookie banner,
-docs sidebar), or it is a per-template bar such as a sticky mobile buy bar.
-
-**Shape:** one global, created once and placed by the layout. Links are rows of `{label, link}`;
-a call to action is one button; design (sticky, transparent, tone) is a setting, never copy.
-Breadcrumbs and the sticky mobile bar are not globals: the first is per page and mostly automatic,
-the second sits on the template it appears on.
-
-**Traps:** a link field for the logo (it always goes home); copying a cart count, prices or the
-customer name (session state, `nav-ecommerce-header`); free-text opening hours
-(`footer-mega-locations`); a countdown stored as text (`announcement-countdown`); pre-ticked
-optional consent categories (`cookie-consent`); the hamburger markup (the renderer's job,
-`nav-simple-cta`).
-
-| Entry | Pick it when |
-|---|---|
-| `nav-simple-cta` | Logo, a short link row, one button, maybe a tel: link |
-| `nav-announcement-utility` | Stacked rows: a one-sentence strip, a utility row, the main nav |
-| `nav-mega-featured-promo` | Top items open panels with headed columns, product cards and a promo tile |
-| `nav-docs-sidebar` | The same nav tree on every /docs page; auto from the page tree when order matches the URLs |
-| `nav-ecommerce-header` | Search, account and cart controls; collection links |
-| `nav-locale-header` | Language and currency switchers; the same header in every locale |
-| `sticky-mobile-cta-bar` | position fixed at the bottom, one button, shown on phones |
-| `announcement-countdown` | A separate dismissible strip with a countdown or rotating messages |
-| `cookie-consent` | A consent banner with category toggles (unless a vendor CMP script owns it: report it) |
-| `breadcrumb-config` | A crumb trail; auto when every crumb is a prefix of the current path |
-| `footer-multi-column` | Headed link groups, a newsletter form, socials, payment badges |
-| `footer-minimal` | No headings and under about eight links |
-| `footer-mega-locations` | Locations with addresses, hours and map links, app badges |
-
-### Heroes
-
-**When:** the page's opening band: one `h1`, a lede, one or two buttons, a media column or a
-background.
-
-**Shape:** plain strings for eyebrow, heading and body; buttons as button units; one media slot
-whose type (image, video, gallery) is a select revealing its own fields (`hero-split-media`).
-Live data comes through a reference (a product, a testimonial), forms through a form reference,
-dates as datetimes with an offset.
-
-**Traps:** price, SKU or stock copied into the hero (`hero-product`); a count-up read mid-animation
-as "0" (`hero-stats`); QR or store-badge images uploaded instead of their links
-(`hero-app-download`); raw CSS gradients stored as strings (`hero-centered-gradient`); every
-audience holding a full copy of the hero (`hero-personalized`).
-
-| Entry | Pick it when |
-|---|---|
-| `hero-split-media` | Text column plus one media column (image, video or a few images) |
-| `hero-centered-gradient` | Centered `h1`, an optional pill link, a gradient background, a screenshot |
-| `hero-video-fullbleed` | A background `<video>` behind the text; needs captions, poster and a text alternative |
-| `hero-slider` | Several full-width slides from a carousel library |
-| `hero-product` | A product form at the top: pickers, add to cart |
-| `hero-search` | A search form is the main control |
-| `hero-lead-form` | A hero beside a form of a few inputs |
-| `hero-app-download` | App store badges, maybe a QR code and device screens |
-| `hero-stats` | Two to four big numerals in the hero |
-| `hero-logo-wall` | A strip of customer logos under the hero copy |
-| `hero-split-testimonial` | A quote card beside or over the hero image |
-| `hero-event` | A date, a place and a ticket button |
-| `hero-personalized` | Hidden variants in the DOM or different copy per UTM or region |
-
-### Features & storytelling
-
-**When:** bands that explain the product: grids of features, rows of text and media, steps,
-timelines, tabs, comparisons, stats, a manifesto.
-
-**Shape:** a list of same-shaped items inside one band. Column count, side and layout direction
-are variants. Media per item is a select revealing image or video. Numbers are value, prefix and
-suffix; dates carry their precision.
-
-**Traps:** a free `columns` number (`feature-icon-grid`); a stored step number
-(`steps-how-it-works`); a `side` on every row, which breaks the zigzag on reorder
-(`feature-alternating-rows`); a bare year in a date field (`timeline-company-history`); FAQ
-markup on rows that are not questions (`accordion-feature-image-swap`); comparative claims with
-no date (`comparison-vs-competitors`).
-
-| Entry | Pick it when |
-|---|---|
-| `feature-icon-grid` | Same-shaped cards: small icon, title, text, optional link |
-| `feature-alternating-rows` | Text and media rows that flip sides |
-| `bento-feature-showcase` | Grid cells with different spans and different inner shapes |
-| `steps-how-it-works` | Numbered steps, maybe a connector line |
-| `timeline-company-history` | Dated milestones on a line |
-| `tabs-with-media` | Same-shaped tab panels with an image or video each (different shapes: core `tabs`) |
-| `accordion-feature-image-swap` | Accordion rows with one image per row |
-| `comparison-vs-competitors` | Brand columns with check and cross cells |
-| `stats-band` | A row of big numbers with labels and footnoted sources |
-| `manifesto-pull-quote` | One large quote, or several short display lines |
-| `problem-solution` | Two lists, problems and fixes, paired |
-| `integrations-grid` | Logo tiles linking to /integrations pages, filter chips |
-
-### Social proof
-
-**When:** testimonials, video stories, a wall of social posts, case study cards, logos, press,
-awards, a review summary.
-
-**Shape:** testimonials, case studies and reviews are collection entries the section references,
-by pick or by query (tags, limit, minimum rating). Logos are rows of name plus file. Awards carry
-a kind that changes what is required (certificate id and expiry for certifications).
-
-**Traps:** inlined quotes that drift from the approved wording (`testimonial-grid`); a logo named
-"logo" (`logo-cloud`); marquee duplicates imported twice (`logo-cloud`); expired certifications
-shown as current, or "HIPAA certified" (`awards-certifications`); self-serving Review or
-AggregateRating markup (`testimonial-grid`, `review-summary`); hosted video without captions
-(`testimonial-video-slider`).
-
-| Entry | Pick it when |
-|---|---|
-| `testimonial-grid` | Three or more quote cards with name and role |
-| `testimonial-video-slider` | Slides that are videos or quotes |
-| `wall-of-love` | Mixed social posts, store reviews and photo posts |
-| `case-study-cards` | Customer cards linking to story pages with a metric |
-| `logo-cloud` | Logos only, no quotes |
-| `press-mentions` | Outlet logos with quotes linking to articles |
-| `awards-certifications` | Badges: awards, certifications, memberships |
-| `review-summary` | An average, a star distribution, "based on N reviews" |
-
-### Media & galleries
-
-**When:** photo grids, filtered galleries, video, before and after, hotspots, 3D or Lottie, mixed
-carousels, a full-bleed image with overlay text, a social photo feed.
-
-**Shape:** image rows with alt, caption and a separate credit; per-breakpoint columns as design;
-positions as percentages; the video source a select between a link and a hosted file.
-
-**Traps:** the thumbnail imported instead of the full file (`masonry-gallery`); credits pasted
-into captions (`masonry-gallery`); pixel hotspot positions (`image-hotspots`); a 40 MB model or
-an un-vetted iframe host (`interactive-3d-lottie-embed`); cloned slides (`mixed-media-carousel`);
-UGC widget scripts and photo rights assumed (`ugc-social-feed`).
-
-| Entry | Pick it when |
-|---|---|
-| `masonry-gallery` | Many photos in CSS columns or masonry, a lightbox |
-| `lightbox-gallery-filters` | Filter buttons over a photo grid |
-| `video-section` | A YouTube, Vimeo or hosted video with captions and chapters |
-| `before-after-slider` | Two stacked images, one clipped, a handle |
-| `image-hotspots` | Positioned pins on an image opening a product or a note |
-| `interactive-3d-lottie-embed` | `<model-viewer>`, a Lottie player or an allow-listed 3D iframe |
-| `mixed-media-carousel` | Slides of different kinds: photo, video, quote, product |
-| `parallax-image-overlay` | One full-bleed image with text on top |
-| `ugc-social-feed` | A grid of social photos from an account, a hashtag or hand-picked |
-
-### Commerce
-
-**When:** product grids, a product page, a featured product, collection filters, bundles, cart
-offers, a promo with a code, shop the look, size guides, store locators, product comparisons.
-
-**Shape:** products are referenced (a Products entry linked to the store product); a grid stores
-a query or picked references; a product page is a Products entry, not a block; size guides and
-comparisons use the `table` type keyed by column.
-
-**Traps:** prices, compare-at prices, options, variants or stock copied into content
-(`commerce-product-detail`, `commerce-product-grid-query`); facet values imported as content
-(`commerce-collection-header-facets`); an invented discount code (`commerce-bundle-builder`); a
-deadline without an offset (`commerce-promo-countdown`); inches converted to centimetres
-(`commerce-size-guide`); map API keys imported (`commerce-store-locator`).
-
-| Entry | Pick it when |
-|---|---|
-| `commerce-product-grid-query` | Product cards sharing a rule (one collection, "New") or picked |
-| `commerce-product-detail` | The product page itself: gallery, options, specs, policies |
-| `commerce-featured-product` | One product spotlighted, maybe with add to cart |
-| `commerce-collection-header-facets` | A collection header with filter groups and sort |
-| `commerce-bundle-builder` | Choose N products, tiered or fixed bundle price |
-| `commerce-cart-cross-sell` | Upsell offers in the cart, a free-shipping threshold |
-| `commerce-promo-countdown` | A promo strip with a code and a timer |
-| `commerce-shop-the-look` | Looks: images with product dots |
-| `commerce-size-guide` | Size tables, maybe a unit toggle, measuring steps |
-| `commerce-store-locator` | A map beside an address list, hours, holiday exceptions |
-| `commerce-product-comparison` | Two to four products side by side |
-
-### Pricing & plans
-
-**When:** plan cards with a billing switch, usage calculators, feature matrices, a single plan
-with add-ons, enterprise contact, pricing FAQs, a pay-yearly banner.
-
-**Shape:** both cycle prices written per plan (never derived by a percentage); per-seat, free and
-custom pricing as a select; "Everything in X, plus" as inheritance with only the new bullets; the
-matrix as a `table` keyed by plan key; payment price ids developer-locked.
-
-**Traps:** a "Save 20%" badge that is not true for every plan (`pricing-tiers-billing-toggle`);
-a formula stored as a string (`pricing-usage-calculator`); pre-checked paid add-ons
-(`pricing-single-plan-addons`); contact fields inlined instead of a form reference
-(`pricing-enterprise-card`); two FAQPage blocks on one URL (`pricing-faq`); a saving not computed
-from real prices (`pricing-annual-savings-banner`).
-
-| Entry | Pick it when |
-|---|---|
-| `pricing-tiers-billing-toggle` | Plan cards with a monthly or yearly switch |
-| `pricing-usage-calculator` | Range sliders and a live total from graduated rates |
-| `pricing-feature-matrix` | A large table of plans against features |
-| `pricing-single-plan-addons` | One plan plus optional extras with units |
-| `pricing-enterprise-card` | A contact-sales card: form, calendar link or plain link |
-| `pricing-faq` | Grouped questions on the pricing page, maybe price tokens in answers |
-| `pricing-annual-savings-banner` | A banner urging monthly payers to switch |
-
-### Conversion & forms
-
-**When:** CTA bands, newsletter sign-up, lead capture, multi-step forms, booking embeds, waitlists,
-contact sections, quizzes, popups, trust badges.
-
-**Shape:** a section holds presentation and a Form reference; inputs belong to the Form document
-([forms-and-interactions.md](forms-and-interactions.md)). Success behaviour (message, redirect,
-download) is a select. Booking widgets store the provider and its id only.
-
-**Traps:** a per-section copy of the inputs, which forks submissions (`conversion-lead-capture`);
-placeholder-only labels (`conversion-newsletter-consent`); a pre-ticked consent box
-(`conversion-newsletter-consent`); a widget script stored as HTML (`conversion-booking-embed`); a
-static "join 12,000 others" number (`conversion-waitlist-referral`); guessed quiz weights
-(`conversion-quiz-product-finder`); a popup on checkout or full-screen on phones
-(`conversion-exit-intent-popup`); typed review scores (`conversion-trust-badges`).
-
-| Entry | Pick it when |
-|---|---|
-| `conversion-cta-band` | Heading, one sentence, one or two buttons, no inputs |
-| `conversion-newsletter-consent` | One email input with consent |
-| `conversion-lead-capture` | Copy beside a multi-field form with a success state |
-| `conversion-multi-step-form` | Fieldsets with Next and Back, branching |
-| `conversion-booking-embed` | Resy, OpenTable, Tock or Cal widget |
-| `conversion-waitlist-referral` | A launch waitlist with referral rewards |
-| `conversion-contact-section` | Email, phone and chat channels, a form, a map |
-| `conversion-quiz-product-finder` | Questions that end in product recommendations |
-| `conversion-exit-intent-popup` | A dialog on exit, delay, scroll or click (one global per dialog) |
-| `conversion-trust-badges` | A row of guarantees, shipping, certifications, payment icons |
-
-### Listings & feeds
-
-**When:** blog indexes, category filter bars, related posts, resource libraries, podcast episode
-lists, changelogs, roadmaps, search results.
-
-**Shape:** the section stores a query against a collection (filters, sort, page size,
-pagination), with pinned or featured picks as references. Items are entries imported first.
-Related posts go on the post template, not on each post.
-
-**Traps:** nine visible cards frozen into an inline list (`blog-index`); typed chip labels
-(`category-filter-bar`); picks on a template, which apply to every post (`related-posts`); facets
-on non-indexed fields (`resource-library`); an embed iframe instead of the RSS audio
-(`podcast-episode-list`); free-text change badges (`changelog`); editable vote counts
-(`public-roadmap`); search results imported or a noindex field added (`search-results-page`).
-
-| Entry | Pick it when |
-|---|---|
-| `blog-index` | Article cards with dates and a shared href prefix |
-| `category-filter-bar` | Topic chips that filter a list or navigate |
-| `related-posts` | Two to four cards after an article |
-| `resource-library` | Typed resources with facet filters and gated downloads |
-| `podcast-episode-list` | Show details, platform links and an episode list |
-| `changelog` | Version or date headings with typed changes |
-| `public-roadmap` | Stage columns of items, votes, a suggestion form |
-| `search-results-page` | The /search page: sources, pins, empty state |
-
-### Long-form & docs
-
-**When:** a page whose main content is one body: articles, docs, knowledge-base answers, recipes,
-legal policies, case studies, podcast episodes; or a block inside such a page (author box, code
-tabs, glossary, curriculum).
-
-**Shape:** most entries here are collection entries, not components (their notCarried says
-`kind:entry`): title, slug, dates, references to authors and topics, and ONE rich-text body with
-islands for callouts, tables, code, images, video and component instances
-([portable-text.md](portable-text.md)). Structured parts (ingredients, sections and clauses,
-modules and lessons, chapters) are lists, not prose.
-
-**Traps:** an `h1` in the body (`rich-blog-post`); the author box copied instead of referenced
-(`rich-blog-post`, `author-bio`); the on-page table of contents imported (`docs-page`); hard-coded
-prev and next (`docs-page`); highlighted code `<span>` soup (`code-tabs`); letter headings stored
-as terms (`glossary`); ingredient lines as plain strings (`recipe`); typed clause numbers and
-changed anchors (`legal-policy`); durations as text (`course-curriculum`); the episode embed
-instead of the audio file (`podcast-episode`).
-
-| Entry | Pick it when |
-|---|---|
-| `rich-blog-post` | An article with a byline, cover and rich body (entry) |
-| `author-bio` | An author box under posts (on the template) |
-| `docs-page` | A docs article with sidebar position, admonitions and pager (entry) |
-| `code-tabs` | One example in several languages, synced tabs |
-| `kb-article` | A help answer with "Was this helpful?" (entry) |
-| `glossary` | Terms and definitions with a letter index |
-| `recipe` | Ingredients, steps, times and nutrition (entry) |
-| `course-curriculum` | Modules of lessons with types and free previews |
-| `legal-policy` | Numbered sections and clauses, effective date, versions (entry) |
-| `case-study` | Customer facts, metrics, challenge, solution, results (entry) |
-| `podcast-episode` | One episode: audio, notes, chapters, transcript (entry) |
-
-### Company & people
-
-**When:** team grids, leadership bios, values and culture, careers, job postings, about and
-timeline, press kits.
-
-**Shape:** people are People entries referenced from the section (by query or pick), with
-per-placement overrides for title or bio. Jobs are Jobs entries or synced from a hiring system.
-Asset groups in a press kit are lists of assets with formats.
-
-**Traps:** people retyped per page (`team-grid`); the CEO duplicated for the board group
-(`leadership-bios`); job rows copied into the careers section (`careers-list`); salary minimum
-above maximum, which the schema cannot catch (`job-posting`); closed roles deleted instead of
-closed (`job-posting`); year ranges stored as strings (`about-timeline`); photos without credit
-(`press-kit`).
-
-| Entry | Pick it when |
-|---|---|
-| `team-grid` | Headshots with name and role, maybe department tabs |
-| `leadership-bios` | Leadership, board and advisor groups with bio modals |
-| `values-culture` | Values with examples, perks, a culture photo wall |
-| `careers-list` | Open roles from the site or a hiring system |
-| `job-posting` | One job page (entry) |
-| `about-timeline` | Mission, story, founders, milestones |
-| `press-kit` | Downloadable logos and photos, boilerplate, facts, coverage |
-
-### Events & places
-
-**When:** events lists, conference pages, webinar registration, location directories, restaurant
-menus, single location pages.
-
-**Shape:** events and locations are entries; a list stores a query and splits upcoming from past
-by computing it. Datetimes carry an offset or a separate zone. Opening hours are rows per day
-(closed flag, one or more shifts), with special-hours rows for holidays. Menus nest menus,
-sections, items and price variants.
-
-**Traps:** past events flagged "upcoming" by hand (`events-list`); agenda times in the visitor's
-zone (`event-detail`); speakers typed into session titles (`event-detail`); a separate replay page
-instead of switching the webinar stage (`webinar-registration`); hours as one text line
-(`locations-directory`); overnight closing read as earlier than opening (`location-page`);
-"$18 / $32" in one price (`restaurant-menu`); allergen data no owner signed off
-(`restaurant-menu`).
-
-| Entry | Pick it when |
-|---|---|
-| `events-list` | Upcoming and past events as list, cards, calendar or map |
-| `event-detail` | One conference: days, sessions, speakers, venue, ticket tiers (entry) |
-| `webinar-registration` | One webinar across upcoming, live and on demand |
-| `locations-directory` | Map plus list of many locations with hours and services |
-| `restaurant-menu` | Menus, sections, dishes, prices, dietary tags |
-| `location-page` | One location's page: address, hours, booking (entry) |
-
-### Data & interactive
-
-**When:** spec tables, comparison tables, charts, calculators, product configurators, maps with
-markers, product comparison sliders, countdowns and live counters, polls, embeds, code snippets.
-
-**Shape:** tables use the `table` type: typed, keyed columns, a caption, row headers, row groups,
-footnotes; more than about 60 rows comes from a CSV or a collection (`data-table-specs`). Charts
-store their data as series and points, plus a required one-sentence summary
-(`chart-attrition`). Calculators store typed inputs and outputs whose formulas name input keys
-(`roi-calculator`). Maps store markers with geopoints and keep a list beside the map
-(`stockist-map`). Embeds store a URL or provider id with a required title (`safe-embed`).
-
-**Traps:** a rasterised chart, or values read off bar heights without review
-(`chart-attrition`); an approximated formula, which should stay a code component with copy
-fields only (`roi-calculator`); rules by index instead of keys (`product-configurator`); product
-names typed into a comparison (`product-compare-slider`); a local time without a zone
-(`countdown-live-counter`); a fabricated live counter or a per-visitor countdown
-(`countdown-live-counter`); vote counts imported, or a survey nested in a poll (`reader-poll`);
-tracking pixels or chat widgets migrated as embeds (`safe-embed`); highlighted HTML stored as
-code (`code-snippet-tabs`).
-
-| Entry | Pick it when |
-|---|---|
-| `data-table-specs` | A spec table with typed columns, maybe from a CSV or collection |
-| `table-comparison` | The reference table: typed columns, groups, footnotes, notes |
-| `chart-attrition` | A chart with series, axes and annotations |
-| `roi-calculator` | Inputs that feed computed outputs |
-| `product-configurator` | Steps of options with price deltas and availability rules |
-| `stockist-map` | A map with categorised markers and popups |
-| `product-compare-slider` | Products compared by attributes, swipe on phones |
-| `countdown-live-counter` | A countdown to a launch, maybe a live counter |
-| `reader-poll` | One question with options, a scale or an open answer |
-| `safe-embed` | Any iframe, oEmbed URL or script widget |
-| `code-snippet-tabs` | A code block with tabs per language or package manager |
-
-### Advanced patterns
-
-**When:** the shape itself is the hard part: deep nesting, mixed item types, conditional sources,
-globals with overrides, translations, personalization, responsive settings, grids with per-cell
-layout, reference webs, nested validation, rich text with components, query listings, overlays,
-scrollytelling, accessibility-critical media, section theme tokens.
-
-**Shape and traps:** each entry is the long form of one [edge tag](#edge-tags); read the tag rule
-first, then the entry. Most of their pitfalls are SCHEMA GAPs: listed in
-[Gaps the kit names](#gaps-the-kit-names).
-
-| Entry | Pick it when | Tag rule |
-|---|---|---|
-| `page-builder-six-deep` | Tabs holding columns holding accordions holding cards | deep-nesting |
-| `polymorphic-modules` | An article built from mixed module types | polymorphic-array |
-| `conditional-source-matrix` | One section whose items come manually, from a collection, a query or an external service | conditional |
-| `global-announcement-overrides` | A bar on most pages whose copy differs on a few | global-synced |
-| `localized-section` | Copy in several locales, right-to-left included | localized |
-| `personalized-hero` | Audience segments and an A/B split on one hero | personalization |
-| `responsive-layout-settings` | Columns, gap and spacing that differ per breakpoint | responsive-layout |
-| `grid-cell-layout` | A grid whose cells set their own span, surface and alignment | slots |
-| `references-web` | Products, authors, recipes and pages linked, pinned and auto-filled | references |
-| `changelog-nested-validation` | Releases of changes with semver and issue-key patterns | validation |
-| `rich-text-embedded-components` | A body with component islands, footnotes and glossary terms | rich-text |
-| `dynamic-query-listing` | A listing defined by filters, sort, limit and pins | dynamic-query |
-| `overlays-with-triggers` | Modals, drawers and popovers opened by triggers | slots |
-| `scrollytelling` | Sticky media that changes as text steps scroll past | media-heavy |
-| `a11y-critical-media-form` | Video with captions and transcript, image roles, a labelled form | a11y |
-| `section-theme-tokens` | A dark or brand-coloured section inside a light page | variants |
-
-### Core examples
-
-Seven original examples (`core-hero`, `core-faq`, `core-pricing`, `core-tabs`, `core-bento`,
-`core-megaMenu`, `core-journalStory`). They carry a schema and a sample value but no notes:
-use them as reference shapes and take the guidance from the matching category above
-(`core-bento` is worked through end to end in [worked-examples.md](worked-examples.md) §9).
-
-## Edge tags
-
-An edge tag names one modelling difficulty. Every entry lists its tags; a section you build
-inherits the rules of every tag it has.
-
-### deep-nesting
-
-Count levels where the content changes kind, not DOM wrappers: same-shaped siblings are a list,
-siblings that differ are slot children (`page-builder-six-deep`). Up to six content levels stay in
-one section; past six, or past about ten children at a level, split the deepest repeated subtree
-into its own block. Never make one thing both a list item and a slot. Keep the deepest tiny rows
-inline (sizes in `restaurant-menu`, resources in `course-curriculum`). A sidebar deeper than four
-levels is flattened and reported (`nav-docs-sidebar`). Cases: `core-megaMenu`,
-`nav-mega-featured-promo`, `commerce-product-detail`, `conversion-quiz-product-finder`,
-`press-kit`, `event-detail`, `location-page`.
-
-### repeater
-
-Same-shaped items in one band are one list in one section, never one section per item
-(`feature-alternating-rows`). Never store what order already says: a step number
-(`steps-how-it-works`), clause numbering (`legal-policy`), a totals line (`course-curriculum`).
-Dedupe clones a carousel or marquee adds (`hero-slider`, `logo-cloud`). Unequal paired lists are
-flagged, never truncated (`problem-solution`). Long lists move to a collection: 60+ releases
-(`changelog`), 300 glossary terms (`glossary`). Plain strings are a string list, not rows of one
-field (`hero-split-media` points).
-
-### polymorphic-array
-
-One list whose items have different shapes: each item names its type, and the editor picks the
-type on add (`polymorphic-modules`). Classify each item by its dominant element: a figure is an
-image item, a blockquote a quote item, a big numeral a stat item, else text
-(`polymorphic-modules`, `wall-of-love`, `mixed-media-carousel`). Merge consecutive paragraphs into
-one text item; one item per paragraph is the commonest bad conversion. Over about 40 items, or
-mostly prose, use a rich-text body with islands instead. On a component this is a `table` prop in
-types mode (playbook §5). Cases: `commerce-product-detail` gallery,
-`conversion-multi-step-form` fields, `core-tabs`, `core-bento`.
-
-### slots
-
-Blocks placed inside a block: the children differ in shape and the editor chooses them
-(`core-tabs`, `core-bento`). Per-child layout (span, surface, alignment, order on phones) goes
-in the slot's settings, never on the child's own fields, or reusing the child elsewhere carries a
-meaningless span (`bento-feature-showcase`, `grid-cell-layout`). Validate spans against the
-variant's column count. Regular same-shaped cells are a plain card list, not a slot
-(`grid-cell-layout`). Overlays hold their own slot content, and their triggers are `#id` links
-(`overlays-with-triggers`). A marketer-owned promo tile beside structured menu columns is a slot
-(`nav-mega-featured-promo`). Worked example: [worked-examples.md](worked-examples.md) §9.
-
-### variants
-
-Layout choices are variants of one section, never a free number or boolean the editor can break:
-column count (`feature-icon-grid`), image side (`commerce-featured-product`), grid versus carousel
-(`commerce-product-grid-query`), striped or compact tables (`data-table-specs`). Pick the variant
-from the rendered layout. A field that only one variant uses cannot be hidden by the variant
-today, so its help text says which variant reads it (`conversion-cta-band`). Theme (dark section,
-accent, spacing) maps to brand tokens, never stored hex or pixels (`section-theme-tokens`).
-
-### conditional
-
-A select (source, kind, mode, type) reveals only the fields of its branch: media type
-(`hero-split-media`), pick versus query (`testimonial-grid`), source manual, collection, query or
-external (`conditional-source-matrix`), success message, redirect or download
-(`conversion-lead-capture`). Fill only the active branch: hidden values are kept and published.
-A condition reads one sibling only, so a child cannot react to its parent (the quiz picture
-field in `conversion-quiz-product-finder`, the swatch in `product-configurator`), and toggles do
-not chain (`countdown-live-counter`). Decide the source from how the items got there, never how
-they look; a snapshot of a dynamic list is never frozen into a manual one.
-
-### references
-
-Link to the existing entry, product or page instead of copying its title, photo or price; store
-only what differs as an override (`commerce-featured-product`, `case-study-cards`,
-`leadership-bios`). Resolve every link before creating anything, and create missing targets as
-entries first (`references-web`, `case-study-cards`). Match existing entries before creating (by
-name plus the first 40 characters of a quote, `testimonial-grid`). Chips and filters reference a
-taxonomy collection, never typed labels (`category-filter-bar`, `integrations-grid`). A
-reference by id survives slug changes; a stored href does not. Picks belong to the instance, not
-the template (`related-posts`).
-
-### dynamic-query
-
-A listing stores the query (collection, filters, sort, limit, pagination, pins), never copies of
-the cards; otherwise new items never appear (`blog-index`, `dynamic-query-listing`,
-`commerce-product-grid-query`). Infer the query by comparing the listing across pages and over
-time. Create the collection and import the items as entries first, then place the block. A
-hand-curated list with no shared rule is a references list instead. Search, related posts and
-synced job boards configure a source and import nothing (`search-results-page`, `related-posts`,
-`careers-list`). An empty result hides the block; never add placeholder items.
-
-### global-synced
-
-An element repeated with the same content on most pages (the kit says 80%) is one global,
-created once from the most common version (`global-announcement-overrides`). Pages that differ
-get an instance overriding only the differing fields; a page without it hides the instance. If
-more than half the fields differ on more than a third of pages, it is a normal block. Header,
-footer, announcement, cookie banner, docs sidebar and popups are globals in the kit
-(`nav-simple-cta`, `footer-multi-column`, `cookie-consent`, `nav-docs-sidebar`,
-`conversion-exit-intent-popup`); in BetterCMS chrome is the Global Layout. A field synced from a
-global inside a normal block (store links in `hero-app-download`) is written to the global too.
-
-### localized
-
-Crawl every locale and match the same section by position and structure, never by text
-(`localized-section`, `nav-locale-header`). The default locale fills the fields; each other locale
-carries its copy, direction (rtl for ar, he, fa, ur) and a status; a missing locale is recorded
-as missing. Never translate during conversion, and flag legal text for per-locale review
-(`legal-policy`). Link to the page and let locale routing resolve it, never typed /de/ URLs; never
-model hreflang (`nav-locale-header`). A header that differs in structure per locale is a
-per-market header, not a translation. Languages are codes, not flags. Sort term lists with the
-locale's collation (`glossary`). Keep credits out of translatable captions (`masonry-gallery`).
-Platform locales: [localization.md](localization.md).
-
-### rich-text
-
-An article body is one rich-text field. Non-prose elements become islands: figure to image,
-table to table, aside to callout, details to toggle, a known card to a component instance with
-overrides (`rich-blog-post`, `rich-text-embedded-components`). Template chrome (share bar, author
-box, related cards, the table of contents) is not body content. Demote an `h1` in the body.
-Footnotes are keyed annotations with their text held beside the body; internal links resolve to
-entries. An island used in more than one article must be a library component. Split a body only
-where the layout needs it (challenge, solution, results in `case-study`). Shapes:
-[portable-text.md](portable-text.md).
-
-### media-heavy
-
-Import the largest source (lightbox href or the biggest srcset entry), keep real alt text, and
-never "logo", "image" or "team photo" (`masonry-gallery`, `logo-cloud`, `values-culture`). Video
-needs a poster (extract or generate one) and, when it has speech, captions; a missing caption
-file is flagged, never invented (`hero-video-fullbleed`, `testimonial-video-slider`). Positions on
-an image are percentages (`image-hotspots`, `commerce-shop-the-look`). Art-directed phone images
-are their own field (`parallax-image-overlay`, `hero-slider`). Keep logos' original files and never
-recolour them in content (`integrations-grid`, `press-mentions`). Sticky-panel media lives on the
-step it belongs to (`scrollytelling`).
-
-### embed
-
-Store the provider and its id, or the canonical URL, never the widget script or its HTML
-(`conversion-booking-embed`, `safe-embed`, `ugc-social-feed`). An iframe needs a title; write one
-if missing. Only allow-listed hosts go into the embed block; anything else becomes a developer
-task (`interactive-3d-lottie-embed`). Tracking pixels, analytics and chat widgets are site
-settings, not embeds (`safe-embed`). Never import API keys (`commerce-store-locator`,
-`stockist-map`). Prefer importing the underlying data over an embed: RSS audio over a player
-iframe (`podcast-episode-list`), a public roadmap's JSON over its iframe (`public-roadmap`), code
-as plain text with highlighting at render (`code-tabs`, `code-snippet-tabs`).
-
-### form
-
-A section references a Form document by id; it never holds the inputs (`hero-lead-form`,
-`conversion-lead-capture`, `pricing-enterprise-card`). Match an existing form by its inputs or
-list id before creating one, and tag a shared list instead of making one form per launch
-(`conversion-waitlist-referral`). Per-placement settings are allowed: hidden attribution fields,
-a submit label that differs, success behaviour. Static hidden values only; never store personal
-data from the URL. A sequence of questions is a Form, not a poll (`reader-poll`). Third-party
-form embeds (HubSpot, Typeform) are reported with their id. Rules:
-[forms-and-interactions.md](forms-and-interactions.md).
-
-### commerce
-
-The store owns price, compare-at price, SKU, stock, options, variants, cart and currency: reference
-the product and never copy them (`commerce-product-detail`, `hero-product`,
-`nav-ecommerce-header`). Flag any currency typed into copy. "Add to cart" is an action, not a link
-(`sticky-mobile-cta-bar`). Discounts need a real store discount behind them; never invent a code
-(`commerce-bundle-builder`, `commerce-cart-cross-sell`). Facet values are computed from products
-(`commerce-collection-header-facets`). Typed review scores and ratings go stale; prefer a
-connected source (`review-summary`, `conversion-trust-badges`). Menus and plan prices are numbers
-without symbols (`restaurant-menu`, `pricing-tiers-billing-toggle`).
-Storefront rules: [shopify-headless.md](shopify-headless.md).
-
-### personalization
-
-Model personalization only with evidence: hidden variants in the DOM, an experiment tool's
-config, or URLs you were given per audience (`hero-personalized`, `personalized-hero`). The
-version shown without parameters is the complete default; each audience stores only the fields
-that differ, and order decides when two match. Never import third-party experiment ids as
-content. Crawlers and the page title see the default. A test that rewrites more than one section
-is a page-level experiment. Audience targeting also shapes promo and cart offers
-(`commerce-promo-countdown`, `commerce-cart-cross-sell`, `pricing-annual-savings-banner`,
-`conversion-exit-intent-popup`, `conversion-quiz-product-finder`). Experiments on variants:
-[content-experiments.md](content-experiments.md).
-
-### validation
-
-Store values in their real type: numbers as value plus prefix and suffix (count-up safe, "1.2k"
-stays 1.2 and "k"; `stats-band`, `hero-stats`), datetimes with an offset (`hero-event`,
-`announcement-countdown`), dates with their precision (`timeline-company-history`), times as
-24-hour HH:MM (`commerce-store-locator`). Required fields exist for a reason: a certification's
-expiry (`awards-certifications`), a comparison's last-checked date
-(`comparison-vs-competitors`), a migration note on a breaking change
-(`changelog-nested-validation`). Cross-field rules (end after start, minimum under maximum,
-weights summing to 100) cannot be declared; check them at import and flag them. Server checks:
-[write-limits.md](write-limits.md).
-
-### a11y
-
-Every visual-only element gets text: logo names (`logo-cloud`), hotspot labels
-(`commerce-shop-the-look`), iframe titles (`safe-embed`), email labels
-(`conversion-newsletter-consent`), carousel names (`hero-slider`), words in yes or no cells
-(`comparison-vs-competitors`). Images are decorative (empty alt), informative or complex with a
-long description (`a11y-critical-media-form`, `parallax-image-overlay`). Captions and a transcript
-are separate things; model both, and leave captions empty rather than auto-generate them
-(`hero-video-fullbleed`). A map keeps its list (`stockist-map`, `locations-directory`). Focus
-trap, Esc and focus return, pause on hover and reduced motion are the renderer's, never toggles
-(`overlays-with-triggers`, `tabs-with-media`). Audit rules: [accessibility.md](accessibility.md).
-
-### seo-structured
-
-Structured data is emitted by the platform from content; never model meta fields, JSON-LD fields
-or an SEO group (playbook §5b, [seo.md](seo.md)). Fill the content it reads instead (dates, prices
-by reference, hours as rows, geopoints) and verify the output matches the source's markup
-(`breadcrumb-config`, `footer-mega-locations`, `recipe`, `job-posting`, `location-page`). Emit
-only what is eligible: no Review markup for your own testimonials (`testimonial-grid`), no
-AggregateRating without a product subject (`review-summary`), no HowTo for steps
-(`steps-how-it-works`), one FAQPage per URL (`pricing-faq`), award markup for awards only
-(`awards-certifications`), a table's ItemList only when it is the page's offer
-(`table-comparison`). Personalized copy is never the indexed version.
-
-### responsive-layout
-
-Read the computed layout at desktop, tablet and phone widths rather than parsing CSS
-(`responsive-layout-settings`). Store per-breakpoint values as settings, with tablet inheriting
-desktop unless it differs; spacing maps to tokens, never pixels. Phones stack, carousel or grid;
-capture a reorder (`mobileOrder`) rather than hiding content, because hidden content is hidden
-from mobile-first indexing too. Visibility per breakpoint and per-cell spans live in settings
-(`sticky-mobile-cta-bar`, `bento-feature-showcase`, `grid-cell-layout`). Production today: a
-slot item's `style.hideOn` hides it at a breakpoint ([components.md](components.md)).
-
-## Gaps the kit names
-
-Pitfalls marked SCHEMA GAP are rules the schema language cannot express yet. Check them yourself
-and flag what you cannot:
-
-- Cross-field and cross-item rules: end after start, min under max, weights to 100, compare-at
-  above price (`hero-event`, `commerce-product-detail`, `personalized-hero`).
-- Options or references drawn from a sibling field: a marker's category from the categories list,
-  a default sort column from the table's columns (`stockist-map`, `data-table-specs`).
-- References inside one entry: a quiz branch or a plan's "Everything in" naming another item by a
-  free string, which a rename breaks silently (`conversion-quiz-product-finder`,
-  `pricing-tiers-billing-toggle`).
-- Conditions that read a parent, chain, or combine with AND or OR (`conditional-source-matrix`).
-- Enforced uniqueness of keys and ids (`overlays-with-triggers`, `changelog-nested-validation`).
-- Formula, responsive, token-reference, time-of-day and address types (`roi-calculator`,
-  `responsive-layout-settings`, `section-theme-tokens`, `commerce-store-locator`, `stockist-map`).
-- What a rich-text field allows, and typed annotations (`rich-text-embedded-components`).
+---
+title: "Kit scenarios"
+description: "Which component-kit entry fits a section and what to do for it: all 14 kit categories and all 20 edge tags, each with when to pick it, the field shape, the pitfalls and real kit entry ids, plus what a stored component cannot carry."
+---
+
+# Kit scenarios: pick the closest kit entry, then model it
+
+The component kit is 149 worked section patterns (142 kit entries in 14 categories, plus 7 core
+examples). Each entry carries notes written for a converting agent: what the section is, the HTML
+that gives it away, the mapping to fields, and the mistakes to avoid. The full list is the MCP
+resource `bettercms://kit` (an index: categories, tags and one line per entry, each with the URI
+of its category and of the entry itself) and the generated reference
+[kit-catalog.md](kit-catalog.md). This file is the hand-written chooser that points into it.
+
+## Contents
+
+- [How to use the kit](#how-to-use-the-kit)
+- [What a stored component cannot carry](#what-a-stored-component-cannot-carry)
+- [Categories](#categories)
+- [Edge tags](#edge-tags)
+- [Gaps the kit names](#gaps-the-kit-names)
+
+## How to use the kit
+
+1. **Name the band's category** from the chooser below (or detection.md §7). The category decides
+   where the section lives: chrome goes in the Global Layout, a record type becomes a collection,
+   everything else is a section component or page fields.
+2. **Pick the closest entry.** Inside the category, match the strongest HTML signal; the chooser
+   lists what separates each entry from its neighbours. Then read that entry's own resource from
+   the index: its `mcp` note is the mapping, its `pitfalls` are the review list, its `htmlSignals`
+   are what to look for, and its `component` is the props list the kit converts to (step 4).
+3. **Check its edge tags** against the [edge tag rules](#edge-tags). A band that matches no entry
+   still has tags (a list of cards is `repeater`; a price is `commerce`), and the tag rules hold
+   for it.
+4. **Never send an entry's props to `create_component` as they are.** The catalogue's props have
+   no `target`; every prop you declare needs one, aimed at the leaf your own `blockJson` renders
+   for it (schema playbook §3, [components.md](components.md) §1). Write the `blockJson` first.
+5. **Copy the shape, never the sample copy.** The entries use a fictional cookware brand
+   (Ember, Hearth & Ash, Sierra camp). Write the customer's words.
+6. **Respect the entry's limits.** A pitfall that starts "SCHEMA GAP" is something the platform
+   cannot check; do the check yourself at import time and flag what you cannot.
+
+## What a stored component cannot carry
+
+Each catalogue entry lists `notCarried`: kit features the stored component drops. Do the
+production equivalent instead of losing the intent.
+
+| notCarried | What to do instead |
+|---|---|
+| `variants` | Each layout variant is its own component sharing one `sectionType`, same prop keys ([components.md](components.md)) |
+| `kind:global` | The section is chrome: the Global Layout (`get_layout`, `update_layout`), never a page section |
+| `kind:entry (props)` | The entry is a record: a collection model and entries, not a component |
+| `slot allow` | Name the allowed child components with the slot prop's `config.componentIds` |
+| `reference target` | Point the reference at a collection with `config.contentModelId` |
+| `ai`, `category`, `item openMode`, `item settings`, `group (nested)`, `fieldset (derived)`, `document preview path`, `segmented>4`, `validation.items`, `itemNoun (derived)` | Editor presentation only; arrange the dock with [editor-chrome.md](editor-chrome.md) where it matters |
+
+## Categories
+
+Each category: when it applies, the shape, the traps, and a chooser of every entry in it.
+
+### Navigation & chrome
+
+**When:** the band is the same on every page (header, footer, announcement bar, cookie banner,
+docs sidebar), or it is a per-template bar such as a sticky mobile buy bar.
+
+**Shape:** one global, created once and placed by the layout. Links are rows of `{label, link}`;
+a call to action is one button; design (sticky, transparent, tone) is a setting, never copy.
+Breadcrumbs and the sticky mobile bar are not globals: the first is per page and mostly automatic,
+the second sits on the template it appears on.
+
+**Traps:** a link field for the logo (it always goes home); copying a cart count, prices or the
+customer name (session state, `nav-ecommerce-header`); free-text opening hours
+(`footer-mega-locations`); a countdown stored as text (`announcement-countdown`); pre-ticked
+optional consent categories (`cookie-consent`); the hamburger markup (the renderer's job,
+`nav-simple-cta`).
+
+| Entry | Pick it when |
+|---|---|
+| `nav-simple-cta` | Logo, a short link row, one button, maybe a tel: link |
+| `nav-announcement-utility` | Stacked rows: a one-sentence strip, a utility row, the main nav |
+| `nav-mega-featured-promo` | Top items open panels with headed columns, product cards and a promo tile |
+| `nav-docs-sidebar` | The same nav tree on every /docs page; auto from the page tree when order matches the URLs |
+| `nav-ecommerce-header` | Search, account and cart controls; collection links |
+| `nav-locale-header` | Language and currency switchers; the same header in every locale |
+| `sticky-mobile-cta-bar` | position fixed at the bottom, one button, shown on phones |
+| `announcement-countdown` | A separate dismissible strip with a countdown or rotating messages |
+| `cookie-consent` | A consent banner with category toggles (unless a vendor CMP script owns it: report it) |
+| `breadcrumb-config` | A crumb trail; auto when every crumb is a prefix of the current path |
+| `footer-multi-column` | Headed link groups, a newsletter form, socials, payment badges |
+| `footer-minimal` | No headings and under about eight links |
+| `footer-mega-locations` | Locations with addresses, hours and map links, app badges |
+
+### Heroes
+
+**When:** the page's opening band: one `h1`, a lede, one or two buttons, a media column or a
+background.
+
+**Shape:** plain strings for eyebrow, heading and body; buttons as button units; one media slot
+whose type (image, video, gallery) is a select revealing its own fields (`hero-split-media`).
+Live data comes through a reference (a product, a testimonial), forms through a form reference,
+dates as datetimes with an offset.
+
+**Traps:** price, SKU or stock copied into the hero (`hero-product`); a count-up read mid-animation
+as "0" (`hero-stats`); QR or store-badge images uploaded instead of their links
+(`hero-app-download`); raw CSS gradients stored as strings (`hero-centered-gradient`); every
+audience holding a full copy of the hero (`hero-personalized`).
+
+| Entry | Pick it when |
+|---|---|
+| `hero-split-media` | Text column plus one media column (image, video or a few images) |
+| `hero-centered-gradient` | Centered `h1`, an optional pill link, a gradient background, a screenshot |
+| `hero-video-fullbleed` | A background `<video>` behind the text; needs captions, poster and a text alternative |
+| `hero-slider` | Several full-width slides from a carousel library |
+| `hero-product` | A product form at the top: pickers, add to cart |
+| `hero-search` | A search form is the main control |
+| `hero-lead-form` | A hero beside a form of a few inputs |
+| `hero-app-download` | App store badges, maybe a QR code and device screens |
+| `hero-stats` | Two to four big numerals in the hero |
+| `hero-logo-wall` | A strip of customer logos under the hero copy |
+| `hero-split-testimonial` | A quote card beside or over the hero image |
+| `hero-event` | A date, a place and a ticket button |
+| `hero-personalized` | Hidden variants in the DOM or different copy per UTM or region |
+
+### Features & storytelling
+
+**When:** bands that explain the product: grids of features, rows of text and media, steps,
+timelines, tabs, comparisons, stats, a manifesto.
+
+**Shape:** a list of same-shaped items inside one band. Column count, side and layout direction
+are variants. Media per item is a select revealing image or video. Numbers are value, prefix and
+suffix; dates carry their precision.
+
+**Traps:** a free `columns` number (`feature-icon-grid`); a stored step number
+(`steps-how-it-works`); a `side` on every row, which breaks the zigzag on reorder
+(`feature-alternating-rows`); a bare year in a date field (`timeline-company-history`); FAQ
+markup on rows that are not questions (`accordion-feature-image-swap`); comparative claims with
+no date (`comparison-vs-competitors`).
+
+| Entry | Pick it when |
+|---|---|
+| `feature-icon-grid` | Same-shaped cards: small icon, title, text, optional link |
+| `feature-alternating-rows` | Text and media rows that flip sides |
+| `bento-feature-showcase` | Grid cells with different spans and different inner shapes |
+| `steps-how-it-works` | Numbered steps, maybe a connector line |
+| `timeline-company-history` | Dated milestones on a line |
+| `tabs-with-media` | Same-shaped tab panels with an image or video each (different shapes: core `tabs`) |
+| `accordion-feature-image-swap` | Accordion rows with one image per row |
+| `comparison-vs-competitors` | Brand columns with check and cross cells |
+| `stats-band` | A row of big numbers with labels and footnoted sources |
+| `manifesto-pull-quote` | One large quote, or several short display lines |
+| `problem-solution` | Two lists, problems and fixes, paired |
+| `integrations-grid` | Logo tiles linking to /integrations pages, filter chips |
+
+### Social proof
+
+**When:** testimonials, video stories, a wall of social posts, case study cards, logos, press,
+awards, a review summary.
+
+**Shape:** testimonials, case studies and reviews are collection entries the section references,
+by pick or by query (tags, limit, minimum rating). Logos are rows of name plus file. Awards carry
+a kind that changes what is required (certificate id and expiry for certifications).
+
+**Traps:** inlined quotes that drift from the approved wording (`testimonial-grid`); a logo named
+"logo" (`logo-cloud`); marquee duplicates imported twice (`logo-cloud`); expired certifications
+shown as current, or "HIPAA certified" (`awards-certifications`); self-serving Review or
+AggregateRating markup (`testimonial-grid`, `review-summary`); hosted video without captions
+(`testimonial-video-slider`).
+
+| Entry | Pick it when |
+|---|---|
+| `testimonial-grid` | Three or more quote cards with name and role |
+| `testimonial-video-slider` | Slides that are videos or quotes |
+| `wall-of-love` | Mixed social posts, store reviews and photo posts |
+| `case-study-cards` | Customer cards linking to story pages with a metric |
+| `logo-cloud` | Logos only, no quotes |
+| `press-mentions` | Outlet logos with quotes linking to articles |
+| `awards-certifications` | Badges: awards, certifications, memberships |
+| `review-summary` | An average, a star distribution, "based on N reviews" |
+
+### Media & galleries
+
+**When:** photo grids, filtered galleries, video, before and after, hotspots, 3D or Lottie, mixed
+carousels, a full-bleed image with overlay text, a social photo feed.
+
+**Shape:** image rows with alt, caption and a separate credit; per-breakpoint columns as design;
+positions as percentages; the video source a select between a link and a hosted file.
+
+**Traps:** the thumbnail imported instead of the full file (`masonry-gallery`); credits pasted
+into captions (`masonry-gallery`); pixel hotspot positions (`image-hotspots`); a 40 MB model or
+an un-vetted iframe host (`interactive-3d-lottie-embed`); cloned slides (`mixed-media-carousel`);
+UGC widget scripts and photo rights assumed (`ugc-social-feed`).
+
+| Entry | Pick it when |
+|---|---|
+| `masonry-gallery` | Many photos in CSS columns or masonry, a lightbox |
+| `lightbox-gallery-filters` | Filter buttons over a photo grid |
+| `video-section` | A YouTube, Vimeo or hosted video with captions and chapters |
+| `before-after-slider` | Two stacked images, one clipped, a handle |
+| `image-hotspots` | Positioned pins on an image opening a product or a note |
+| `interactive-3d-lottie-embed` | `<model-viewer>`, a Lottie player or an allow-listed 3D iframe |
+| `mixed-media-carousel` | Slides of different kinds: photo, video, quote, product |
+| `parallax-image-overlay` | One full-bleed image with text on top |
+| `ugc-social-feed` | A grid of social photos from an account, a hashtag or hand-picked |
+
+### Commerce
+
+**When:** product grids, a product page, a featured product, collection filters, bundles, cart
+offers, a promo with a code, shop the look, size guides, store locators, product comparisons.
+
+**Shape:** products are referenced (a Products entry linked to the store product); a grid stores
+a query or picked references; a product page is a Products entry, not a block; size guides and
+comparisons use the `table` type keyed by column.
+
+**Traps:** prices, compare-at prices, options, variants or stock copied into content
+(`commerce-product-detail`, `commerce-product-grid-query`); facet values imported as content
+(`commerce-collection-header-facets`); an invented discount code (`commerce-bundle-builder`); a
+deadline without an offset (`commerce-promo-countdown`); inches converted to centimetres
+(`commerce-size-guide`); map API keys imported (`commerce-store-locator`).
+
+| Entry | Pick it when |
+|---|---|
+| `commerce-product-grid-query` | Product cards sharing a rule (one collection, "New") or picked |
+| `commerce-product-detail` | The product page itself: gallery, options, specs, policies |
+| `commerce-featured-product` | One product spotlighted, maybe with add to cart |
+| `commerce-collection-header-facets` | A collection header with filter groups and sort |
+| `commerce-bundle-builder` | Choose N products, tiered or fixed bundle price |
+| `commerce-cart-cross-sell` | Upsell offers in the cart, a free-shipping threshold |
+| `commerce-promo-countdown` | A promo strip with a code and a timer |
+| `commerce-shop-the-look` | Looks: images with product dots |
+| `commerce-size-guide` | Size tables, maybe a unit toggle, measuring steps |
+| `commerce-store-locator` | A map beside an address list, hours, holiday exceptions |
+| `commerce-product-comparison` | Two to four products side by side |
+
+### Pricing & plans
+
+**When:** plan cards with a billing switch, usage calculators, feature matrices, a single plan
+with add-ons, enterprise contact, pricing FAQs, a pay-yearly banner.
+
+**Shape:** both cycle prices written per plan (never derived by a percentage); per-seat, free and
+custom pricing as a select; "Everything in X, plus" as inheritance with only the new bullets; the
+matrix as a `table` keyed by plan key; payment price ids developer-locked.
+
+**Traps:** a "Save 20%" badge that is not true for every plan (`pricing-tiers-billing-toggle`);
+a formula stored as a string (`pricing-usage-calculator`); pre-checked paid add-ons
+(`pricing-single-plan-addons`); contact fields inlined instead of a form reference
+(`pricing-enterprise-card`); two FAQPage blocks on one URL (`pricing-faq`); a saving not computed
+from real prices (`pricing-annual-savings-banner`).
+
+| Entry | Pick it when |
+|---|---|
+| `pricing-tiers-billing-toggle` | Plan cards with a monthly or yearly switch |
+| `pricing-usage-calculator` | Range sliders and a live total from graduated rates |
+| `pricing-feature-matrix` | A large table of plans against features |
+| `pricing-single-plan-addons` | One plan plus optional extras with units |
+| `pricing-enterprise-card` | A contact-sales card: form, calendar link or plain link |
+| `pricing-faq` | Grouped questions on the pricing page, maybe price tokens in answers |
+| `pricing-annual-savings-banner` | A banner urging monthly payers to switch |
+
+### Conversion & forms
+
+**When:** CTA bands, newsletter sign-up, lead capture, multi-step forms, booking embeds, waitlists,
+contact sections, quizzes, popups, trust badges.
+
+**Shape:** a section holds presentation and a Form reference; inputs belong to the Form document
+([forms-and-interactions.md](forms-and-interactions.md)). Success behaviour (message, redirect,
+download) is a select. Booking widgets store the provider and its id only.
+
+**Traps:** a per-section copy of the inputs, which forks submissions (`conversion-lead-capture`);
+placeholder-only labels (`conversion-newsletter-consent`); a pre-ticked consent box
+(`conversion-newsletter-consent`); a widget script stored as HTML (`conversion-booking-embed`); a
+static "join 12,000 others" number (`conversion-waitlist-referral`); guessed quiz weights
+(`conversion-quiz-product-finder`); a popup on checkout or full-screen on phones
+(`conversion-exit-intent-popup`); typed review scores (`conversion-trust-badges`).
+
+| Entry | Pick it when |
+|---|---|
+| `conversion-cta-band` | Heading, one sentence, one or two buttons, no inputs |
+| `conversion-newsletter-consent` | One email input with consent |
+| `conversion-lead-capture` | Copy beside a multi-field form with a success state |
+| `conversion-multi-step-form` | Fieldsets with Next and Back, branching |
+| `conversion-booking-embed` | Resy, OpenTable, Tock or Cal widget |
+| `conversion-waitlist-referral` | A launch waitlist with referral rewards |
+| `conversion-contact-section` | Email, phone and chat channels, a form, a map |
+| `conversion-quiz-product-finder` | Questions that end in product recommendations |
+| `conversion-exit-intent-popup` | A dialog on exit, delay, scroll or click (one global per dialog) |
+| `conversion-trust-badges` | A row of guarantees, shipping, certifications, payment icons |
+
+### Listings & feeds
+
+**When:** blog indexes, category filter bars, related posts, resource libraries, podcast episode
+lists, changelogs, roadmaps, search results.
+
+**Shape:** the section stores a query against a collection (filters, sort, page size,
+pagination), with pinned or featured picks as references. Items are entries imported first.
+Related posts go on the post template, not on each post.
+
+**Traps:** nine visible cards frozen into an inline list (`blog-index`); typed chip labels
+(`category-filter-bar`); picks on a template, which apply to every post (`related-posts`); facets
+on non-indexed fields (`resource-library`); an embed iframe instead of the RSS audio
+(`podcast-episode-list`); free-text change badges (`changelog`); editable vote counts
+(`public-roadmap`); search results imported or a noindex field added (`search-results-page`).
+
+| Entry | Pick it when |
+|---|---|
+| `blog-index` | Article cards with dates and a shared href prefix |
+| `category-filter-bar` | Topic chips that filter a list or navigate |
+| `related-posts` | Two to four cards after an article |
+| `resource-library` | Typed resources with facet filters and gated downloads |
+| `podcast-episode-list` | Show details, platform links and an episode list |
+| `changelog` | Version or date headings with typed changes |
+| `public-roadmap` | Stage columns of items, votes, a suggestion form |
+| `search-results-page` | The /search page: sources, pins, empty state |
+
+### Long-form & docs
+
+**When:** a page whose main content is one body: articles, docs, knowledge-base answers, recipes,
+legal policies, case studies, podcast episodes; or a block inside such a page (author box, code
+tabs, glossary, curriculum).
+
+**Shape:** most entries here are collection entries, not components (their notCarried says
+`kind:entry`): title, slug, dates, references to authors and topics, and ONE rich-text body with
+islands for callouts, tables, code, images, video and component instances
+([portable-text.md](portable-text.md)). Structured parts (ingredients, sections and clauses,
+modules and lessons, chapters) are lists, not prose.
+
+**Traps:** an `h1` in the body (`rich-blog-post`); the author box copied instead of referenced
+(`rich-blog-post`, `author-bio`); the on-page table of contents imported (`docs-page`); hard-coded
+prev and next (`docs-page`); highlighted code `<span>` soup (`code-tabs`); letter headings stored
+as terms (`glossary`); ingredient lines as plain strings (`recipe`); typed clause numbers and
+changed anchors (`legal-policy`); durations as text (`course-curriculum`); the episode embed
+instead of the audio file (`podcast-episode`).
+
+| Entry | Pick it when |
+|---|---|
+| `rich-blog-post` | An article with a byline, cover and rich body (entry) |
+| `author-bio` | An author box under posts (on the template) |
+| `docs-page` | A docs article with sidebar position, admonitions and pager (entry) |
+| `code-tabs` | One example in several languages, synced tabs |
+| `kb-article` | A help answer with "Was this helpful?" (entry) |
+| `glossary` | Terms and definitions with a letter index |
+| `recipe` | Ingredients, steps, times and nutrition (entry) |
+| `course-curriculum` | Modules of lessons with types and free previews |
+| `legal-policy` | Numbered sections and clauses, effective date, versions (entry) |
+| `case-study` | Customer facts, metrics, challenge, solution, results (entry) |
+| `podcast-episode` | One episode: audio, notes, chapters, transcript (entry) |
+
+### Company & people
+
+**When:** team grids, leadership bios, values and culture, careers, job postings, about and
+timeline, press kits.
+
+**Shape:** people are People entries referenced from the section (by query or pick), with
+per-placement overrides for title or bio. Jobs are Jobs entries or synced from a hiring system.
+Asset groups in a press kit are lists of assets with formats.
+
+**Traps:** people retyped per page (`team-grid`); the CEO duplicated for the board group
+(`leadership-bios`); job rows copied into the careers section (`careers-list`); salary minimum
+above maximum, which the schema cannot catch (`job-posting`); closed roles deleted instead of
+closed (`job-posting`); year ranges stored as strings (`about-timeline`); photos without credit
+(`press-kit`).
+
+| Entry | Pick it when |
+|---|---|
+| `team-grid` | Headshots with name and role, maybe department tabs |
+| `leadership-bios` | Leadership, board and advisor groups with bio modals |
+| `values-culture` | Values with examples, perks, a culture photo wall |
+| `careers-list` | Open roles from the site or a hiring system |
+| `job-posting` | One job page (entry) |
+| `about-timeline` | Mission, story, founders, milestones |
+| `press-kit` | Downloadable logos and photos, boilerplate, facts, coverage |
+
+### Events & places
+
+**When:** events lists, conference pages, webinar registration, location directories, restaurant
+menus, single location pages.
+
+**Shape:** events and locations are entries; a list stores a query and splits upcoming from past
+by computing it. Datetimes carry an offset or a separate zone. Opening hours are rows per day
+(closed flag, one or more shifts), with special-hours rows for holidays. Menus nest menus,
+sections, items and price variants.
+
+**Traps:** past events flagged "upcoming" by hand (`events-list`); agenda times in the visitor's
+zone (`event-detail`); speakers typed into session titles (`event-detail`); a separate replay page
+instead of switching the webinar stage (`webinar-registration`); hours as one text line
+(`locations-directory`); overnight closing read as earlier than opening (`location-page`);
+"$18 / $32" in one price (`restaurant-menu`); allergen data no owner signed off
+(`restaurant-menu`).
+
+| Entry | Pick it when |
+|---|---|
+| `events-list` | Upcoming and past events as list, cards, calendar or map |
+| `event-detail` | One conference: days, sessions, speakers, venue, ticket tiers (entry) |
+| `webinar-registration` | One webinar across upcoming, live and on demand |
+| `locations-directory` | Map plus list of many locations with hours and services |
+| `restaurant-menu` | Menus, sections, dishes, prices, dietary tags |
+| `location-page` | One location's page: address, hours, booking (entry) |
+
+### Data & interactive
+
+**When:** spec tables, comparison tables, charts, calculators, product configurators, maps with
+markers, product comparison sliders, countdowns and live counters, polls, embeds, code snippets.
+
+**Shape:** tables use the `table` type: typed, keyed columns, a caption, row headers, row groups,
+footnotes; more than about 60 rows comes from a CSV or a collection (`data-table-specs`). Charts
+store their data as series and points, plus a required one-sentence summary
+(`chart-attrition`). Calculators store typed inputs and outputs whose formulas name input keys
+(`roi-calculator`). Maps store markers with geopoints and keep a list beside the map
+(`stockist-map`). Embeds store a URL or provider id with a required title (`safe-embed`).
+
+**Traps:** a rasterised chart, or values read off bar heights without review
+(`chart-attrition`); an approximated formula, which should stay a code component with copy
+fields only (`roi-calculator`); rules by index instead of keys (`product-configurator`); product
+names typed into a comparison (`product-compare-slider`); a local time without a zone
+(`countdown-live-counter`); a fabricated live counter or a per-visitor countdown
+(`countdown-live-counter`); vote counts imported, or a survey nested in a poll (`reader-poll`);
+tracking pixels or chat widgets migrated as embeds (`safe-embed`); highlighted HTML stored as
+code (`code-snippet-tabs`).
+
+| Entry | Pick it when |
+|---|---|
+| `data-table-specs` | A spec table with typed columns, maybe from a CSV or collection |
+| `table-comparison` | The reference table: typed columns, groups, footnotes, notes |
+| `chart-attrition` | A chart with series, axes and annotations |
+| `roi-calculator` | Inputs that feed computed outputs |
+| `product-configurator` | Steps of options with price deltas and availability rules |
+| `stockist-map` | A map with categorised markers and popups |
+| `product-compare-slider` | Products compared by attributes, swipe on phones |
+| `countdown-live-counter` | A countdown to a launch, maybe a live counter |
+| `reader-poll` | One question with options, a scale or an open answer |
+| `safe-embed` | Any iframe, oEmbed URL or script widget |
+| `code-snippet-tabs` | A code block with tabs per language or package manager |
+
+### Advanced patterns
+
+**When:** the shape itself is the hard part: deep nesting, mixed item types, conditional sources,
+globals with overrides, translations, personalization, responsive settings, grids with per-cell
+layout, reference webs, nested validation, rich text with components, query listings, overlays,
+scrollytelling, accessibility-critical media, section theme tokens.
+
+**Shape and traps:** each entry is the long form of one [edge tag](#edge-tags); read the tag rule
+first, then the entry. Most of their pitfalls are SCHEMA GAPs: listed in
+[Gaps the kit names](#gaps-the-kit-names).
+
+| Entry | Pick it when | Tag rule |
+|---|---|---|
+| `page-builder-six-deep` | Tabs holding columns holding accordions holding cards | deep-nesting |
+| `polymorphic-modules` | An article built from mixed module types | polymorphic-array |
+| `conditional-source-matrix` | One section whose items come manually, from a collection, a query or an external service | conditional |
+| `global-announcement-overrides` | A bar on most pages whose copy differs on a few | global-synced |
+| `localized-section` | Copy in several locales, right-to-left included | localized |
+| `personalized-hero` | Audience segments and an A/B split on one hero | personalization |
+| `responsive-layout-settings` | Columns, gap and spacing that differ per breakpoint | responsive-layout |
+| `grid-cell-layout` | A grid whose cells set their own span, surface and alignment | slots |
+| `references-web` | Products, authors, recipes and pages linked, pinned and auto-filled | references |
+| `changelog-nested-validation` | Releases of changes with semver and issue-key patterns | validation |
+| `rich-text-embedded-components` | A body with component islands, footnotes and glossary terms | rich-text |
+| `dynamic-query-listing` | A listing defined by filters, sort, limit and pins | dynamic-query |
+| `overlays-with-triggers` | Modals, drawers and popovers opened by triggers | slots |
+| `scrollytelling` | Sticky media that changes as text steps scroll past | media-heavy |
+| `a11y-critical-media-form` | Video with captions and transcript, image roles, a labelled form | a11y |
+| `section-theme-tokens` | A dark or brand-coloured section inside a light page | variants |
+
+### Core examples
+
+Seven original examples (`core-hero`, `core-faq`, `core-pricing`, `core-tabs`, `core-bento`,
+`core-megaMenu`, `core-journalStory`). They carry a schema and a sample value but no notes:
+use them as reference shapes and take the guidance from the matching category above
+(`core-bento` is worked through end to end in [worked-examples.md](worked-examples.md) §9).
+
+## Edge tags
+
+An edge tag names one modelling difficulty. Every entry lists its tags; a section you build
+inherits the rules of every tag it has.
+
+### deep-nesting
+
+Count levels where the content changes kind, not DOM wrappers: same-shaped siblings are a list,
+siblings that differ are slot children (`page-builder-six-deep`). Up to six content levels stay in
+one section; past six, or past about ten children at a level, split the deepest repeated subtree
+into its own block. Never make one thing both a list item and a slot. Keep the deepest tiny rows
+inline (sizes in `restaurant-menu`, resources in `course-curriculum`). A sidebar deeper than four
+levels is flattened and reported (`nav-docs-sidebar`). Cases: `core-megaMenu`,
+`nav-mega-featured-promo`, `commerce-product-detail`, `conversion-quiz-product-finder`,
+`press-kit`, `event-detail`, `location-page`.
+
+### repeater
+
+Same-shaped items in one band are one list in one section, never one section per item
+(`feature-alternating-rows`). Never store what order already says: a step number
+(`steps-how-it-works`), clause numbering (`legal-policy`), a totals line (`course-curriculum`).
+Dedupe clones a carousel or marquee adds (`hero-slider`, `logo-cloud`). Unequal paired lists are
+flagged, never truncated (`problem-solution`). Long lists move to a collection: 60+ releases
+(`changelog`), 300 glossary terms (`glossary`). Plain strings are a string list, not rows of one
+field (`hero-split-media` points).
+
+### polymorphic-array
+
+One list whose items have different shapes: each item names its type, and the editor picks the
+type on add (`polymorphic-modules`). Classify each item by its dominant element: a figure is an
+image item, a blockquote a quote item, a big numeral a stat item, else text
+(`polymorphic-modules`, `wall-of-love`, `mixed-media-carousel`). Merge consecutive paragraphs into
+one text item; one item per paragraph is the commonest bad conversion. Over about 40 items, or
+mostly prose, use a rich-text body with islands instead. On a component this is a `table` prop in
+types mode (playbook §5). Cases: `commerce-product-detail` gallery,
+`conversion-multi-step-form` fields, `core-tabs`, `core-bento`.
+
+### slots
+
+Blocks placed inside a block: the children differ in shape and the editor chooses them
+(`core-tabs`, `core-bento`). Per-child layout (span, surface, alignment, order on phones) goes
+in the slot's settings, never on the child's own fields, or reusing the child elsewhere carries a
+meaningless span (`bento-feature-showcase`, `grid-cell-layout`). Validate spans against the
+variant's column count. Regular same-shaped cells are a plain card list, not a slot
+(`grid-cell-layout`). Overlays hold their own slot content, and their triggers are `#id` links
+(`overlays-with-triggers`). A marketer-owned promo tile beside structured menu columns is a slot
+(`nav-mega-featured-promo`). Worked example: [worked-examples.md](worked-examples.md) §9.
+
+### variants
+
+Layout choices are variants of one section, never a free number or boolean the editor can break:
+column count (`feature-icon-grid`), image side (`commerce-featured-product`), grid versus carousel
+(`commerce-product-grid-query`), striped or compact tables (`data-table-specs`). Pick the variant
+from the rendered layout. A field that only one variant uses cannot be hidden by the variant
+today, so its help text says which variant reads it (`conversion-cta-band`). Theme (dark section,
+accent, spacing) maps to brand tokens, never stored hex or pixels (`section-theme-tokens`).
+
+### conditional
+
+A select (source, kind, mode, type) reveals only the fields of its branch: media type
+(`hero-split-media`), pick versus query (`testimonial-grid`), source manual, collection, query or
+external (`conditional-source-matrix`), success message, redirect or download
+(`conversion-lead-capture`). Fill only the active branch: hidden values are kept and published.
+A condition reads one sibling only, so a child cannot react to its parent (the quiz picture
+field in `conversion-quiz-product-finder`, the swatch in `product-configurator`), and toggles do
+not chain (`countdown-live-counter`). Decide the source from how the items got there, never how
+they look; a snapshot of a dynamic list is never frozen into a manual one.
+
+### references
+
+Link to the existing entry, product or page instead of copying its title, photo or price; store
+only what differs as an override (`commerce-featured-product`, `case-study-cards`,
+`leadership-bios`). Resolve every link before creating anything, and create missing targets as
+entries first (`references-web`, `case-study-cards`). Match existing entries before creating (by
+name plus the first 40 characters of a quote, `testimonial-grid`). Chips and filters reference a
+taxonomy collection, never typed labels (`category-filter-bar`, `integrations-grid`). A
+reference by id survives slug changes; a stored href does not. Picks belong to the instance, not
+the template (`related-posts`).
+
+### dynamic-query
+
+A listing stores the query (collection, filters, sort, limit, pagination, pins), never copies of
+the cards; otherwise new items never appear (`blog-index`, `dynamic-query-listing`,
+`commerce-product-grid-query`). Infer the query by comparing the listing across pages and over
+time. Create the collection and import the items as entries first, then place the block. A
+hand-curated list with no shared rule is a references list instead. Search, related posts and
+synced job boards configure a source and import nothing (`search-results-page`, `related-posts`,
+`careers-list`). An empty result hides the block; never add placeholder items.
+
+### global-synced
+
+An element repeated with the same content on most pages (the kit says 80%) is one global,
+created once from the most common version (`global-announcement-overrides`). Pages that differ
+get an instance overriding only the differing fields; a page without it hides the instance. If
+more than half the fields differ on more than a third of pages, it is a normal block. Header,
+footer, announcement, cookie banner, docs sidebar and popups are globals in the kit
+(`nav-simple-cta`, `footer-multi-column`, `cookie-consent`, `nav-docs-sidebar`,
+`conversion-exit-intent-popup`); in BetterCMS chrome is the Global Layout. A field synced from a
+global inside a normal block (store links in `hero-app-download`) is written to the global too.
+
+### localized
+
+Crawl every locale and match the same section by position and structure, never by text
+(`localized-section`, `nav-locale-header`). The default locale fills the fields; each other locale
+carries its copy, direction (rtl for ar, he, fa, ur) and a status; a missing locale is recorded
+as missing. Never translate during conversion, and flag legal text for per-locale review
+(`legal-policy`). Link to the page and let locale routing resolve it, never typed /de/ URLs; never
+model hreflang (`nav-locale-header`). A header that differs in structure per locale is a
+per-market header, not a translation. Languages are codes, not flags. Sort term lists with the
+locale's collation (`glossary`). Keep credits out of translatable captions (`masonry-gallery`).
+Platform locales: [localization.md](localization.md).
+
+### rich-text
+
+An article body is one rich-text field. Non-prose elements become islands: figure to image,
+table to table, aside to callout, details to toggle, a known card to a component instance with
+overrides (`rich-blog-post`, `rich-text-embedded-components`). Template chrome (share bar, author
+box, related cards, the table of contents) is not body content. Demote an `h1` in the body.
+Footnotes are keyed annotations with their text held beside the body; internal links resolve to
+entries. An island used in more than one article must be a library component. Split a body only
+where the layout needs it (challenge, solution, results in `case-study`). Shapes:
+[portable-text.md](portable-text.md).
+
+### media-heavy
+
+Import the largest source (lightbox href or the biggest srcset entry), keep real alt text, and
+never "logo", "image" or "team photo" (`masonry-gallery`, `logo-cloud`, `values-culture`). Video
+needs a poster (extract or generate one) and, when it has speech, captions; a missing caption
+file is flagged, never invented (`hero-video-fullbleed`, `testimonial-video-slider`). Positions on
+an image are percentages (`image-hotspots`, `commerce-shop-the-look`). Art-directed phone images
+are their own field (`parallax-image-overlay`, `hero-slider`). Keep logos' original files and never
+recolour them in content (`integrations-grid`, `press-mentions`). Sticky-panel media lives on the
+step it belongs to (`scrollytelling`).
+
+### embed
+
+Store the provider and its id, or the canonical URL, never the widget script or its HTML
+(`conversion-booking-embed`, `safe-embed`, `ugc-social-feed`). An iframe needs a title; write one
+if missing. Only allow-listed hosts go into the embed block; anything else becomes a developer
+task (`interactive-3d-lottie-embed`). Tracking pixels, analytics and chat widgets are site
+settings, not embeds (`safe-embed`). Never import API keys (`commerce-store-locator`,
+`stockist-map`). Prefer importing the underlying data over an embed: RSS audio over a player
+iframe (`podcast-episode-list`), a public roadmap's JSON over its iframe (`public-roadmap`), code
+as plain text with highlighting at render (`code-tabs`, `code-snippet-tabs`).
+
+### form
+
+A section references a Form document by id; it never holds the inputs (`hero-lead-form`,
+`conversion-lead-capture`, `pricing-enterprise-card`). Match an existing form by its inputs or
+list id before creating one, and tag a shared list instead of making one form per launch
+(`conversion-waitlist-referral`). Per-placement settings are allowed: hidden attribution fields,
+a submit label that differs, success behaviour. Static hidden values only; never store personal
+data from the URL. A sequence of questions is a Form, not a poll (`reader-poll`). Third-party
+form embeds (HubSpot, Typeform) are reported with their id. Rules:
+[forms-and-interactions.md](forms-and-interactions.md).
+
+### commerce
+
+The store owns price, compare-at price, SKU, stock, options, variants, cart and currency: reference
+the product and never copy them (`commerce-product-detail`, `hero-product`,
+`nav-ecommerce-header`). Flag any currency typed into copy. "Add to cart" is an action, not a link
+(`sticky-mobile-cta-bar`). Discounts need a real store discount behind them; never invent a code
+(`commerce-bundle-builder`, `commerce-cart-cross-sell`). Facet values are computed from products
+(`commerce-collection-header-facets`). Typed review scores and ratings go stale; prefer a
+connected source (`review-summary`, `conversion-trust-badges`). Menus and plan prices are numbers
+without symbols (`restaurant-menu`, `pricing-tiers-billing-toggle`).
+Storefront rules: [shopify-headless.md](shopify-headless.md).
+
+### personalization
+
+Model personalization only with evidence: hidden variants in the DOM, an experiment tool's
+config, or URLs you were given per audience (`hero-personalized`, `personalized-hero`). The
+version shown without parameters is the complete default; each audience stores only the fields
+that differ, and order decides when two match. Never import third-party experiment ids as
+content. Crawlers and the page title see the default. A test that rewrites more than one section
+is a page-level experiment. Audience targeting also shapes promo and cart offers
+(`commerce-promo-countdown`, `commerce-cart-cross-sell`, `pricing-annual-savings-banner`,
+`conversion-exit-intent-popup`, `conversion-quiz-product-finder`). Experiments on variants:
+[content-experiments.md](content-experiments.md).
+
+### validation
+
+Store values in their real type: numbers as value plus prefix and suffix (count-up safe, "1.2k"
+stays 1.2 and "k"; `stats-band`, `hero-stats`), datetimes with an offset (`hero-event`,
+`announcement-countdown`), dates with their precision (`timeline-company-history`), times as
+24-hour HH:MM (`commerce-store-locator`). Required fields exist for a reason: a certification's
+expiry (`awards-certifications`), a comparison's last-checked date
+(`comparison-vs-competitors`), a migration note on a breaking change
+(`changelog-nested-validation`). Cross-field rules (end after start, minimum under maximum,
+weights summing to 100) cannot be declared; check them at import and flag them. Server checks:
+[write-limits.md](write-limits.md).
+
+### a11y
+
+Every visual-only element gets text: logo names (`logo-cloud`), hotspot labels
+(`commerce-shop-the-look`), iframe titles (`safe-embed`), email labels
+(`conversion-newsletter-consent`), carousel names (`hero-slider`), words in yes or no cells
+(`comparison-vs-competitors`). Images are decorative (empty alt), informative or complex with a
+long description (`a11y-critical-media-form`, `parallax-image-overlay`). Captions and a transcript
+are separate things; model both, and leave captions empty rather than auto-generate them
+(`hero-video-fullbleed`). A map keeps its list (`stockist-map`, `locations-directory`). Focus
+trap, Esc and focus return, pause on hover and reduced motion are the renderer's, never toggles
+(`overlays-with-triggers`, `tabs-with-media`). Audit rules: [accessibility.md](accessibility.md).
+
+### seo-structured
+
+Structured data is emitted by the platform from content; never model meta fields, JSON-LD fields
+or an SEO group (playbook §5b, [seo.md](seo.md)). Fill the content it reads instead (dates, prices
+by reference, hours as rows, geopoints) and verify the output matches the source's markup
+(`breadcrumb-config`, `footer-mega-locations`, `recipe`, `job-posting`, `location-page`). Emit
+only what is eligible: no Review markup for your own testimonials (`testimonial-grid`), no
+AggregateRating without a product subject (`review-summary`), no HowTo for steps
+(`steps-how-it-works`), one FAQPage per URL (`pricing-faq`), award markup for awards only
+(`awards-certifications`), a table's ItemList only when it is the page's offer
+(`table-comparison`). Personalized copy is never the indexed version.
+
+### responsive-layout
+
+Read the computed layout at desktop, tablet and phone widths rather than parsing CSS
+(`responsive-layout-settings`). Store per-breakpoint values as settings, with tablet inheriting
+desktop unless it differs; spacing maps to tokens, never pixels. Phones stack, carousel or grid;
+capture a reorder (`mobileOrder`) rather than hiding content, because hidden content is hidden
+from mobile-first indexing too. Visibility per breakpoint and per-cell spans live in settings
+(`sticky-mobile-cta-bar`, `bento-feature-showcase`, `grid-cell-layout`). Production today: a
+slot item's `style.hideOn` hides it at a breakpoint ([components.md](components.md)).
+
+## Gaps the kit names
+
+Pitfalls marked SCHEMA GAP are rules the schema language cannot express yet. Check them yourself
+and flag what you cannot:
+
+- Cross-field and cross-item rules: end after start, min under max, weights to 100, compare-at
+  above price (`hero-event`, `commerce-product-detail`, `personalized-hero`).
+- Options or references drawn from a sibling field: a marker's category from the categories list,
+  a default sort column from the table's columns (`stockist-map`, `data-table-specs`).
+- References inside one entry: a quiz branch or a plan's "Everything in" naming another item by a
+  free string, which a rename breaks silently (`conversion-quiz-product-finder`,
+  `pricing-tiers-billing-toggle`).
+- Conditions that read a parent, chain, or combine with AND or OR (`conditional-source-matrix`).
+- Enforced uniqueness of keys and ids (`overlays-with-triggers`, `changelog-nested-validation`).
+- Formula, responsive, token-reference, time-of-day and address types (`roi-calculator`,
+  `responsive-layout-settings`, `section-theme-tokens`, `commerce-store-locator`, `stockist-map`).
+- What a rich-text field allows, and typed annotations (`rich-text-embedded-components`).