@bettercms-ai/mcp 0.68.1 → 0.69.0

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

@@ -0,0 +1,450 @@
+---
+title: "Detection: reading a site before modeling it"
+description: "How to read a rendered site or repo before any write: render and structured sources, section boundaries, the section classifier with confidence and tie-breaks, element to field mapping, decoration that is never content, edge cases and review flags."
+---
+
+# Detection: reading a site correctly
+
+**Outcome.** Before the first write you hold a list of bands per page, each with a class, a
+confidence, the fields it needs and the flags a reviewer must see. Nothing on it is invented.
+
+The platform has no crawl or render tool. You read the site with your own browser and fetch
+tools, or from the repo and its build output. The platform's own derive step (`editor_setup`)
+reads the build's HTML files, never the live URL, so anything that exists only after client-side
+JavaScript runs is yours to find and model.
+
+What to do with the reading: [content-modeling.md](content-modeling.md) (pages, collections,
+fields), [componentize.md](componentize.md) (bands into components),
+[bindings.md](bindings.md) (attributes), [portable-text.md](portable-text.md) (rich text values).
+
+## Contents
+
+- Reading: [1. Read order](#1-read-order) · [2. Fetch and render](#2-fetch-and-render) ·
+  [3. Structured sources](#3-structured-sources) · [4. Landmarks and chrome](#4-landmarks-and-chrome) ·
+  [5. Section boundaries](#5-section-boundaries) · [6. Repeats, collections and links](#6-repeats-collections-and-links)
+- Classifying: [7. Section classifier](#7-section-classifier) · [8. Tie-breaks](#8-tie-breaks) ·
+  [9. Fallbacks](#9-fallbacks)
+- Mapping: [10. Element to field](#10-element-to-field) ·
+  [11. Decoration is never content](#11-decoration-is-never-content) · [12. Edge cases](#12-edge-cases)
+- Reporting: [13. Review flags](#13-review-flags) · [14. Most reliable signals](#14-most-reliable-signals) ·
+  [Acceptance](#acceptance)
+
+## 1. Read order
+
+Each step uses the output of the one before. Do not model after step 2.
+
+1. Fetch and render (§2); collect structured sources while the page is open (§3).
+2. Find the landmarks (§4), then cut `main` into bands (§5).
+3. Find repeated shapes, collections and link targets (§6).
+4. Classify each band and record its confidence (§7 to §9).
+5. Map each element to a field: structured sources first, visible text second (§10).
+6. Drop decoration and runtime state (§11), handle the edge cases (§12), record flags (§13).
+
+Read at least three pages: the home page, one inner marketing page, one detail page (a post or
+a product). One page cannot tell chrome from content.
+
+## 2. Fetch and render
+
+| The raw HTML shows | It is | Do |
+|---|---|---|
+| Real headings and paragraphs inside `<main>` | Server-rendered or static | Parse the raw HTML. Render once anyway to catch client-only bands |
+| An empty `#root`, `#__next`, `#app`, and large script bundles | Client-rendered | Render in a browser and read the rendered DOM |
+| `<astro-island>`, `__NEXT_DATA__`, `window.__NUXT__` | Hydrated islands | Parse the HTML, then render to read the islands. Their inline JSON often holds the data |
+
+When you render:
+
+- Wait until the network is idle and the framework root has children with no skeleton classes.
+- Scroll to the bottom in steps, so lazy images and observer-loaded bands appear.
+- Read computed styles at 1440, 834 and 390 px wide, not the CSS source.
+- Let count-up animations finish, or read `data-target` / `data-count`. A number read mid
+  animation is often "0".
+- Dismiss the cookie banner with the most private choice. It is not page content.
+- Open every hidden state: closed accordion rows, inactive tabs, both sides of a billing toggle,
+  `<template>` and `<dialog>` contents. Hidden copy is content.
+
+When the raw HTML and the rendered DOM disagree, the rendered DOM is what a visitor sees. Note
+the difference: the derive step sees only the build HTML, so a band that exists only after
+hydration gets no derived fields and needs declared bindings ([bindings.md](bindings.md) §4).
+
+## 3. Structured sources
+
+Prefer a structured source over visible text for the same fact.
+
+| Source | Holds |
+|---|---|
+| `<script type="application/ld+json">` | Product, Recipe, Event, JobPosting, LocalBusiness, VideoObject, FAQPage facts |
+| `__NEXT_DATA__`, `window.__NUXT__`, `<script type="application/json">` | Page props, product JSON, variants |
+| Library config in inline scripts | Carousel slides per view and autoplay delay, chart series, map markers |
+| `data-*` attributes | `data-target`, `data-end`, `data-lat` / `data-lng`, `data-variant-id`, `data-category` |
+| `<link rel="alternate" type="application/rss+xml">` | Posts, episodes, releases: the cleanest list of entries |
+| `<link rel="alternate" hreflang>` | Which locale copies to read. Never a field ([localization.md](localization.md)) |
+
+JSON-LD you read is evidence for field values, not a field to create ([seo.md](seo.md) §3).
+
+## 4. Landmarks and chrome
+
+| Landmark | Signals | Becomes |
+|---|---|---|
+| Header and nav | `<header>` or `role="banner"` early in `<body>`, a `<nav>`, a logo link to `/` | Global Layout |
+| Announcement bar | A thin full-width strip above the header, one sentence, often a close button | Global Layout, its own section |
+| Main | `<main>`, `role="main"`, or the largest container between header and footer | The page's bands |
+| Sidebar | `<aside>`, a docs nav tree, a filter panel | Docs nav: chrome. A filter panel belongs to its listing band |
+| Footer | `<footer>` or `role="contentinfo"` | Global Layout |
+| Overlays | `<dialog>`, `role="dialog"`, off-canvas drawers | A sitewide modal is chrome. A cart drawer is runtime UI, not modelled |
+
+Chrome is never a page section. Read it with `get_layout`, write it with `update_layout`, bind
+it with `data-bcms-layout-field`, never `data-bcms-field` ([bindings.md](bindings.md) §3,
+[components.md](components.md) §4). `get_componentize_plan` reports a nav, footer or modal group
+as `NOT_A_SECTION` with detail `LAYOUT_CHROME`.
+
+| Comparing the pages you read | Decision |
+|---|---|
+| Header or footer markup is the same on two or more pages | One Layout section. Never one per page |
+| A sitewide band differs on a few pages | Still chrome. Report the pages that differ; do not copy it into each page |
+| More than half of a band's values differ on more than a third of pages | Not chrome. A component placed per page |
+| Same structure and styling, different words, in three or more places | One component. `list_extraction_candidates` finds these |
+| Headers differ in structure by locale | Report it. A per-market header is not a translation |
+
+## 5. Section boundaries
+
+A band is one unit a marketer would move, duplicate or swap. Cut `main` at these signals,
+strongest first. Two signals at the same point make the boundary certain.
+
+1. A direct child of `<main>` that is a `<section>`, an `<article>`, or a wrapper with its own
+   `id` or `aria-labelledby`.
+2. A background change: colour, image, gradient or a theme class (`data-theme="dark"`).
+3. A new `h2` (the `h1` in the first band) that opens a new topic with its own intro.
+4. A vertical gap clearly larger than the gaps inside its neighbours, or a full-width divider.
+5. A change of layout system: a two-column split followed by a three-column grid.
+
+- Consecutive bands that repeat one shape are ONE band with a list (alternating feature rows).
+- Every element belongs to a band. Never leave loose headings, paragraphs or images on a page.
+- A wrapper that only adds padding, max width or a grid is design, not a level.
+- A long-form article is not cut into bands. Its body is one `document` field (at most one per
+  schema, top level).
+- In the model each band is a `group`, a repeater, or keys sharing one prefix (`"hero_title"`,
+  `"hero_subtitle"`), so the componentize lane can find it
+  ([content-modeling.md](content-modeling.md) §4).
+
+## 6. Repeats, collections and links
+
+**Same shape or different shape.** Compare each sibling's sequence of content elements (heading
+level, `p`, `img`, `a`, `svg`, `ul`), ignoring wrappers and classes that only style. Siblings
+match when the sequence is equal and optional parts are missing only at the ends.
+
+| Pattern | Model |
+|---|---|
+| Two or more siblings of one shape (cards, tiers, logos, questions, steps) | A repeater. Inside a component: a `group` or `table` prop |
+| A list of plain strings (check-mark bullets) | An `array` of scalars. No icon field, no link field |
+| Siblings of different kinds in one grid (a card, a quote, a big number) | The section's ordered children. A `slot` prop holds ONE instance, so it is not a list |
+| Same shape, each item linking to its own page | Entries of a collection |
+
+Count content levels, not DOM nodes. Component props nest at most three levels; a deeper subtree
+becomes its own component, placed as a child.
+
+**Collections.** A set of records with one shape and their own URLs.
+
+| Signal | Collection |
+|---|---|
+| Card links share a prefix: `/blog/`, `/customers/`, `/integrations/`, `/events/`, `/careers/`, `/docs/` | One per prefix, named for it |
+| `/authors/<slug>`, `rel="author"` | Authors, referenced from posts |
+| A listing with pagination (`?page=2`, `rel="next"`, "Load more") | The listing's source. Read every page of it |
+| `/products/<handle>`, `cdn.shopify.com` | Products stay in the store ([shopify-headless.md](shopify-headless.md)) |
+
+- One collection and one dynamic detail page, never one page per entry. The pattern takes a
+  single slug segment (`/blog/{slug}`). A nested or dated pattern is not available: report any
+  source URL that needs one (flag `url-pattern`) and plan its redirect.
+- Follow each card link for the full record (body, author, dates). The card is a summary.
+- A listing band is not a field of copied cards: the list page reads the collection in code. On
+  a hosted page it is a `collection` block: with `source: { modelId }` it sits on any page and
+  takes filters, a sort, pinned entries and `excludeCurrent`
+  ([content-modeling.md](content-modeling.md) §2). Pagination and grouping are not available.
+- A hand-picked set (no shared rule, rarely changes) is a `multi-reference` field.
+- No URL per item, one page, under about 30 items: a repeater, not a collection.
+
+**Links.** Resolve each one before you create anything.
+
+| Link | Becomes |
+|---|---|
+| To an author, category or other shared record | A reference. Create the record first: a missing target is refused (400, ref_missing) |
+| To a page on the same site, `#id`, `mailto:`, `tel:`, absolute URL | A `link` value as written. Other schemes are refused |
+| A `<form>` | A Form document placed by id ([forms-and-interactions.md](forms-and-interactions.md)). Never inputs copied into a section |
+| Matches nothing you read | Keep the href, flag `link-unresolved` |
+
+## 7. Section classifier
+
+For each band, find the row whose strong signals all match. One match: classify. Several: §8.
+None: §9. The class picks the component family (`sectionType`) and the fields; it is never a
+field itself.
+
+| Confidence | Evidence | Action |
+|---|---|---|
+| High | A unique structural or vendor signal: `<form action="/cart/add">`, `role="tablist"`, JSON-LD of the right type | Model it |
+| Medium | Layout and wording only | Model it, check it against a second page |
+| Low | Wording only, or two rows tie | Model the simpler shape and flag it (§13) |
+
+| Group | Band | Strong signals |
+|---|---|---|
+| Chrome | Header | Short link list, logo link, one filled button at the end, same on every page |
+| Chrome | Mega menu | A top-level item holding a hidden panel with headed link columns or cards |
+| Chrome | Announcement or promo bar | Strip above the header, close button, a code in `<code>`, digits with `data-end` |
+| Chrome | Footer | Headed link lists, newsletter form, socials, a copyright row; minimal: one row, under about eight links |
+| Hero | Split | Two columns: `h1`, text, one or two buttons, and one media column |
+| Hero | Centered | Centered text at a narrow max width, a pill link above the `h1`, a screenshot below |
+| Hero | Video | `<video autoplay muted loop playsinline>` behind the `h1`, an overlay element |
+| Hero | Slider | `swiper-slide`, `splide__slide`, `aria-roledescription="carousel"`, full-width slides |
+| Hero | Product | `<form action="/cart/add">`, option pickers, product JSON |
+| Hero | Search or lead form | `input type="search"` as the main control; or a form of three to six inputs with a privacy line |
+| Hero | Stats or event | Two to four large numerals with `data-count`; or `<time datetime>`, a place, Event JSON-LD |
+| Features | Icon grid | Three to twelve same-shaped cards: icon of 24 to 48 px, `h3`, one `p`; no image over 64 px |
+| Features | Alternating rows | Text and media rows that flip with `row-reverse`. One band, a rows list |
+| Features | Bento | Grid children with different spans and different inner shapes |
+| Features | Steps or timeline | Items led by "01" or "Step 1" with connector lines; or years on a vertical line |
+| Features | Tabs with media | `role="tablist"` and same-shaped panels |
+| Features | Accordion with image swap | `<details>` or `aria-expanded` rows beside one image per row |
+| Features | Comparison | A table whose header holds brand names, check and cross cells |
+| Features | Stats band | Two to five large numbers with small labels, footnote marks |
+| Proof | Testimonials | Three or more cards with quote, name, role, avatar; `<blockquote>` and `<cite>` |
+| Proof | Case study cards | Customer logo, a bold metric, "Read story" to `/customers/` |
+| Proof | Logo cloud | Four to thirty small logos, one label, no other text |
+| Proof | Press or awards | Publication logos with quotes linking out; or badge images (SOC 2, ISO, "Best of") |
+| Proof | Review summary | A big average, stars, "Based on N reviews", review-app classes (`jdgm-`, `okendo-`, `yotpo-`) |
+| Media | Gallery | Six or more images, CSS columns or a masonry script; filter buttons with `data-filter` |
+| Media | Video | YouTube or Vimeo iframe, `<video><source>`, VideoObject JSON-LD |
+| Media | Before and after | Two stacked images, the top one clipped, a handle or range input |
+| Commerce | Product grid | Cards with image, a `/products/` title link, a currency price, "Shop all" |
+| Commerce | Product detail | One `h1`, a price block, a cart form with a hidden variant id, a specs table |
+| Commerce | Store locator | A map beside a scrolling address list, postcode search, `data-lat` / `data-lng` |
+| Pricing | Plan tiers | Two to four columns: plan name, price with "/mo", a button, a check list; a billing switch |
+| Pricing | Feature matrix | A large table under the plan cards, plan columns, check and cross cells |
+| Pricing | Calculator | Range sliders with listeners, a live total in `<output>`, no submit |
+| Conversion | CTA band | Full-width high-contrast band, one heading, at most one sentence, one or two buttons, no inputs |
+| Conversion | Newsletter | A form with exactly one `type="email"` input, a consent line, a mail-provider action URL |
+| Conversion | Lead capture | Copy and bullets beside a multi-field form; fieldsets with Next and Back for multi-step |
+| Conversion | Contact | `mailto:` and `tel:` links by label, a form, a map iframe, hours |
+| Conversion | Popup | A hidden `role="dialog"` shown on a timer, scroll or mouse leave |
+| Listing | Blog index | `<article>` cards with image, heading link, `<time>`, excerpt; a shared href prefix |
+| Listing | Related posts | "Related" or "Keep reading", two to four cards after `</article>` |
+| Listing | Changelog | Version or date headings, New/Improved/Fixed badges, per-version anchors |
+| Long-form | Blog post | `<article>` with one `h1`, a byline, a hero image, a rich body |
+| Long-form | Docs page | Left nav tree, article, right "On this page" anchors, prev and next |
+| Long-form | Recipe, job, event detail | JSON-LD of that type, or the matching plugin classes |
+| Company | Team or leadership | Headshots with name and role; leadership adds C-level titles, bio modals, Board headings |
+| Data | Table | `<table>` with `<th scope="col">`, more than two rows, a `<caption>` |
+| Data | Chart or map | An `<svg>` with axis ticks or a chart library global; a Leaflet, Mapbox or Google container |
+| Data | Embed or code | A third-party `<iframe>` or script widget; `<pre><code class="language-*">` |
+
+## 8. Tie-breaks
+
+| Close call | Test | Answer |
+|---|---|---|
+| Hero or CTA band | First band after the header and holds the page `h1` | Hero. Its type follows its control (form, search, video, slider, product form, stats) |
+| | One heading, at most one sentence, one or two buttons, no inputs | CTA band |
+| | Holds an email input | Newsletter or lead form, never a CTA band |
+| | Two or more paragraphs, or a list | A feature or content band |
+| Grid, tiers, table or collection (stop at the first yes) | Each item has a price with a period ("/mo") and its own button | Pricing tiers, a repeater. A "Compare all features" grid below is a separate table band |
+| | Two-dimensional facts: rows of one kind, columns of one attribute, short values | A table. A layout `<table>` (nested tables, images, one row) is not |
+| | Each item links to its own page under a shared prefix | A collection and a listing |
+| | Images over 64 px dominate each card | Image card grid; an icon of 24 to 48 px with `h3` and `p` is an icon grid |
+| Testimonials or reviews | Curated quotes with a named person, role, company | Testimonials: a collection, picked by reference |
+| | Many ratings from a review app, an aggregate score | Reviews: the app stays the source. Never type the average or count in as content |
+| Logos | Each links to `/integrations/<slug>` or carries a name and one line | Integrations: a collection |
+| | Each sits with a quote and an external article link | Press mentions |
+| | Badges with certification or award words | Awards |
+| | Logos and one label ("Trusted by") | Logo cloud. Under the hero copy it is part of the hero |
+| Accordion, tabs or FAQ | `role="tablist"`, panels of one shape | Tabs: a repeater. Panels of different shapes: separate children |
+| | Tabs that set a value (sort, unit, billing cycle) | A `select`, not panels |
+| | `<details>` rows with one image per row beside them | Accordion with image swap, not an FAQ |
+| | `<details>` rows phrased as questions | FAQ. FAQPage structured data is never automatic: it needs an explicit `schemaType` ([seo.md](seo.md) §3) |
+| Stats band or stats hero | Holds the page `h1`? | Hero if yes |
+| Code snippet or body code | Inside a long-form article? | A code block in the body if yes |
+| Embed or video | YouTube or Vimeo? | Video; any other host is an embed |
+| Popup or site setting | Cookie banner or age gate? | Not an overlay band. Report the consent tool |
+| Changelog band or collection | Over about 30 releases, or each has its own URL? | Collection |
+| Mega menu or simple nav | Any top-level item with a hidden panel? | Mega menu for that item; the others stay links |
+
+## 9. Fallbacks
+
+| Situation | Do |
+|---|---|
+| No row matches; the band has a heading, text, optional media and buttons | The closest generic shape (split or centered content). Flag `unclassified` |
+| Two rows tie at medium confidence | Take the one with fewer fields. Flag `tie` and name both classes |
+| A widget you cannot read (closed iframe, canvas with no data) | Keep it in code as written. Model only the copy around it. Flag `third-party` |
+| Article modules of unknown shape | Convert what Portable Text accepts; a foreign block needs a renderer and a mapping, or it is named in the report ([portable-text.md](portable-text.md) §5) |
+| Logic you cannot express as fields (formulas, multi-condition rules, quiz weights) | The logic stays in code. Model only the copy. Never approximate. Flag `logic-in-code` |
+
+## 10. Element to field
+
+Field keys are flat and prefixed by their band: `"hero_title"`, `"pricing_tiers"`. Labels name
+what the editor sees ([content-modeling.md](content-modeling.md) §5).
+
+**Text, links and images**
+
+| Element | Field | Rule |
+|---|---|---|
+| Small uppercase or tinted text directly above a heading | text | Only when visually separate from the heading |
+| The band heading | text | A highlighted `<span>` inside it stays in the value with its classes. Never restyle it |
+| Paragraphs with links, bold, lists, or more than one paragraph | richtext | A Portable Text array |
+| Item heading (`h3`, `h4`) | text | Drop typed numbering: "01 Start" is "Start" |
+| Small meta text in a card ("2 min", "Remote") | Its own field | Never inside the title |
+| Quote, with `<cite>` or `figcaption` | text, plus separate name, role and company | Drop quotation marks the markup draws |
+| `<a>` or `<button>` drawn as a button | One `button` field | Never a text field beside a link field: refused as `cta_pair` |
+| A standalone text link ("Learn more") | `link` | An inline link in running text is a mark inside the rich text |
+| Submit button, "Add to cart" | No field | The Form owns its label; a store action is wired in code |
+| `<img>` | image | Take the largest `srcset` entry or the lightbox href, never the thumbnail |
+| `alt=""` or `role="presentation"` | Empty alt text | The empty alt is the signal on the value. Decorative wherever it is used: `update_media` `decorative: true` on the asset |
+| `alt` is "logo", "image", a file name, or missing on a meaningful image | Write one from visible context | Flag `alt-written`. No context: leave it empty, flag `alt-missing`. Never from the file name |
+| `<picture>` with a different photo per width | A second image field for the small screen | Art direction is another photo, not a crop |
+| `object-position` or a focal class | The image value's `focal: { x, y }`, fractions 0 to 1 | "30% 70%" is 0.3 and 0.7. Never a focal field in the model ([media-and-brand.md](media-and-brand.md)) |
+| CSS `background-image` carrying a photo | image | The overlay and gradient are design |
+| A screenshot inside a phone or browser frame | The screenshot only | The frame is design. Baked into the file: keep it, flag |
+| App store badges, payment marks, QR codes | Links by destination | A QR code is its decoded URL. Undecodable: flag |
+
+**Icons**
+
+| Source | Do |
+|---|---|
+| Inline `<svg>` of 16 to 48 px beside a heading or label | An `image` field with `config.media: "icon"`, holding the SVG. An editor swaps it |
+| Icon font class (`ti-*`, `lucide-*`, `fa-*`, `bi-*`) | The same field. The prefix names the pack to export the glyph from |
+| `aria-label`, `sr-only` text or `<title>` on the icon | The field's name, and the label of an icon-only link |
+| Check or cross glyphs in a list or table | Not icons. A list marker (drop it) or a yes/no cell |
+| Icon colour, size, background; text inside an `<svg>` | Design, never fields; SVG text is never bound |
+
+**Video, audio and embeds**
+
+| Source | Do |
+|---|---|
+| `<video>` with `<source>` | The best source as the value, bound through `data-bcms-props` as kind `url` |
+| `poster` | An image field. Captured from a frame because none exists: flag `data-estimated` |
+| `<track>` captions | Keep the file reference. Never generate captions. Speech with none: flag `captions-missing` |
+| A transcript on the page | The asset's transcript, set with `update_media` |
+| YouTube or Vimeo iframe or facade | The canonical watch URL, with any start offset. Do not copy the video into the library |
+| `<audio>`, podcast host iframe | The audio file named by the RSS enclosure, not the iframe |
+| Third-party `<iframe>` | Stays in code; model its `src` only where an editor changes it |
+| Script widget (booking, chat, reviews), tracking pixels | Report provider and id. Never store the script, a key or the widget's HTML |
+
+**Prices, numbers, dates, hours, badges**
+
+| Value | Read as | Never |
+|---|---|---|
+| Price from a store | A reference to the store's product | Copy the price, compare-at price, stock or options |
+| Plan price | Amount, currency and period as separate values. Read both sides of a billing toggle | Derive yearly from monthly by a percentage |
+| "Contact us", "Custom" | The label as text | A made-up number |
+| Stat "$2.4B", "94%", "10k+" | Prefix, value and suffix apart when the site animates the number; else one text value | Expand "1.2M" to 1200000 |
+| Count-up number | The `data-target` / `data-count` value | The mid-animation text |
+| Aggregate rating, review count, "n people joined" | Stays with its connected source. Typed into copy: flag `stale-risk` | Type it in as content |
+| Date | A `date` field, ISO. A bare year or "Spring 2016" stays text | Put "2014" in a date field |
+| Date and time (events, sales, countdowns) | A `datetime` field, ISO with its offset | Guess a zone. None on the page: the value as printed, flag `zone-assumed` |
+| Opening hours | A repeater of seven day rows: opens, closes (24-hour HH:MM), closed. Closes before opens means past midnight | One text line. "Open now" is runtime state |
+| Badge ("New", "Sale", "Beta") | A `select` of the values the site uses | Free text that breaks a filter |
+
+**Lists and tables**
+
+| Source | Field |
+|---|---|
+| `<ul>` of short benefits with check icons | An `array` of strings. The icon is the marker; bind the text's own `<span>` |
+| `<ul>` / `<ol>` inside prose | Flat list items in the rich text |
+| `<ol>` of steps with headings, `<dl>` | A repeater (the step number is derived); a repeater of term and definition pairs |
+| A real data table | In an article: a `table` block in the rich text, where the field accepts it. In a section: a `table` prop, or a repeater of rows |
+| A layout table | Its contents become bands |
+| A div grid that behaves like a table (equal children per row, a header row, `data-label`) | Read it as a table |
+
+Table cells: check, "Yes" and "Included" read as true; cross, "No", a dash or empty read as
+false in a yes/no column. A merged body cell: copy the value into each covered cell and flag
+`merged-cells`. Over about 60 rows: a collection, loaded by code against the Management API.
+
+## 11. Decoration is never content
+
+Create no field for any of these.
+
+- Dividers, `<hr>` used as spacing, connector lines between steps, timeline lines and dots.
+- Blobs, blurred circles, mesh backgrounds, gradients, noise, patterns. A section surface is a
+  closed style token ([media-and-brand.md](media-and-brand.md)), never a hex or a CSS string.
+- Cloned DOM for marquees and looping carousels (`aria-hidden` copies, `.swiper-slide-duplicate`,
+  `.slick-cloned`).
+- Hamburger buttons, carousel arrows and dots, copy buttons, "Print", share bars.
+- Derived content: table of contents, letter bars, totals ("6 modules, 42 lessons"), step and
+  footnote numbers, prev and next pagers, breadcrumbs.
+- Runtime state: cart counts, customer names, live tallies, search results, facet values.
+- Animation choreography: count-up, stagger, scroll reveal, parallax speed.
+- Card backgrounds, borders, shadows, hover and focus states.
+- `sr-only` copies of visible text. When it is the only text of an icon, it is that icon's label.
+
+Arrangement (media left or right, grid or carousel, centered or split) is a variant of the
+component, not content ([components.md](components.md) §3). Never edit a class or a style to
+make the site fit the model.
+
+## 12. Edge cases
+
+| Case | Detect | Do |
+|---|---|---|
+| Duplicate mobile and desktop markup | Two copies, one `hidden md:block`, the other `md:hidden` | Model ONE: the more complete copy. Both elements carry the same address and are edited as one value. A different phone photo is a second image field. There are no per-breakpoint values |
+| Carousel clones, marquees | Swiper, Splide, Slick, Embla classes; a duplicated track with an `aria-hidden` copy | Read originals only. Dedupe by image URL plus heading |
+| Hidden states | `role="tablist"`, `<details>`, `aria-expanded="false"`, `hidden` panels | Read every panel and answer. Note which opens first |
+| Lazy content | `loading="lazy"`, `data-src`, skeletons | Scroll and wait. Read `data-src` / `data-srcset` when `src` is a placeholder |
+| Count-up numbers | `data-count`, `countup`, `odometer` | The data attribute, not the visible text |
+| Locale copies | `/de/`, `/fr/`, hreflang, `<html lang>` | Match bands by position and structure, never by text. Each locale is its own row; never translate, never add a locale field ([localization.md](localization.md)) |
+| Experiments and personalization | Hidden copies with `data-variant`, an experiment SDK, an anti-flicker snippet | Model the version served with no parameters. Report the SDK. Never invent audiences |
+| Pagination, "Load more", infinite scroll | `?page=2`, `rel="next"`, a button fetching JSON | Read every page or the JSON endpoint, so the collection is complete |
+| Client-fetched lists | A recommendations or search API, `data-collection` | Stays in code with its owner ([external-content.md](external-content.md)). Never freeze it into a typed list. Unsure: flag `snapshot-of-feed` |
+| Canvas and WebGL | `<canvas>`, a 3D runtime | Stays in code. A chart: recover its data from the script first |
+| Compliance claims | "HIPAA certified", badges with no date | Keep as written, flag `claim-unverified` |
+| Fabricated urgency | Per-visitor countdown resets, fake counters, pre-ticked consent | Do not migrate a fabricated number. Flag with a neutral rewrite |
+
+## 13. Review flags
+
+The skill asks the user two questions only (authoring preference, media delivery). Detection
+adds none. When the reading leaves a doubt, take the safer shape, write it, and record a flag in
+your report with the page, the band and what you chose. Publishing still needs authorization.
+
+| Flag | When | Default taken |
+|---|---|---|
+| `zone-assumed` | A date and time with no zone on the page | The value as printed, no invented offset |
+| `default-locale-assumed` | Locale copies disagree on which is the default | The `<html lang>` of the unprefixed route |
+| `chrome-unsure` | A chrome candidate that differs on many pages | A per-page component |
+| `variant-unread` | An experiment whose targeting you cannot read | The no-parameter version |
+| `alt-missing` | A QR code you cannot decode, a logo you cannot name, an image with no context | Keep the image, empty alt |
+| `snapshot-of-feed` | A list that may be hand-picked or rule-based | Hand-picked references |
+| `unclassified` / `tie` | No classifier row matched; or two matched at medium confidence | Generic shape; the class with fewer fields, both named |
+| `alt-written` | You wrote alt text, or replaced "logo" or "image" | |
+| `label-from-placeholder` | A form input had only a placeholder | Promoted to its label |
+| `captions-missing` | A video with speech has no `<track>` | |
+| `data-estimated` | A chart read from axis ticks, a first-frame poster | |
+| `merged-cells` | A table body had merged cells | The value copied into each cell |
+| `claim-unverified` | Compliance badges, comparative claims with no date | Kept as written |
+| `link-unresolved` | A link that matches no record or page | The href kept |
+| `stale-risk` | A price, rating or count typed into copy ("Just $165!") | Kept as written |
+| `logic-in-code` | A formula, rule or weight you kept in code | |
+| `third-party` | A vendor widget, consent tool or form you reported and did not rebuild | |
+| `url-pattern` | A source URL the single-slug pattern cannot keep | A redirect planned |
+
+Never:
+
+- Invent captions, audiences, discount codes, review numbers or usage rights.
+- Copy store prices, stock, cart counts or facet values into content.
+- Store scripts, API keys, tracking ids or a provider's HTML.
+- Create SEO, meta, hreflang or JSON-LD fields ([seo.md](seo.md)).
+- Model one fact twice (the footer email and the contact page email). One source, read by both.
+
+## 14. Most reliable signals
+
+When two sources disagree, the one higher in this list wins.
+
+1. JSON-LD of the right type. Trust it over visible text.
+2. Form actions: `/cart/add` (store), a mail-provider host (newsletter), a CRM form host (lead).
+3. ARIA roles: `tablist`, `dialog`, `table`, `search`, `banner`, `contentinfo`, `aria-current`.
+4. A shared URL prefix on card links (a collection); RSS for the full list of entries.
+5. Library class names (`swiper-slide`, `wprm-recipe`, `jdgm-`, `leaflet-container`) and data
+   attributes (`data-target`, `data-end`, `data-lat`, `data-variant-id`).
+6. The same markup on two or three pages: chrome.
+7. Background and theme changes: band boundaries.
+8. Sibling shape: equal means a list, different means separate children.
+
+## Acceptance
+
+- Three or more pages read, rendered where the raw HTML was empty, hidden states opened.
+- Every band on every page has a class, a confidence and its fields. None is loose.
+- Chrome is in the Global Layout, on no page.
+- Every repeated shape is one list; every set with its own URLs is a collection.
+- No field holds decoration, runtime state, a clone or a derived value.
+- Every low-confidence call and every default taken is a named flag in the report.

package/dist/skills/bettercms/references/media-and-brand.md

@@ -73,7 +73,8 @@ H1. Expose typography variants only where the design allows a real choice.
 - **Images.** A stored image value is an object (`url`, `altText`, asset id), never a bare
   string; read it as one. Alt text, decorative state and caption belong to the usage. Keep
   `srcset`/`sizes`, poster, lazy/preload intent and art direction. Decorative images render an
-  empty `alt`; informative ones need text that fits the context.
+  empty `alt`; informative ones need text that fits the context. `update_media` with
+  `decorative: true` marks a library asset decorative, so the audit stops asking for its alt text.
 - **Request the size you render.** Mint resize URLs with `@bettercms-ai/image-url`
   (`urlFor = imageUrlBuilder({ baseUrl: mediaUrl })`, then `urlFor(asset).size(800, 450).url()`;
   also `width`, `format`, `quality`, `fit`, `dpr` 1–3) and a

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

@@ -59,7 +59,21 @@ On a site BetterCMS hosts, a publish applies in place with no build: values, Lay
 page with HTML on disk, and a reorder or removal of sections the build draws from the CMS (every band
 stamped `data-bcms-block`, measured in CMS order). Only what needs new markup builds, by itself: a
 new or removed page, a new section or one whose component changed, a Layout structure change, SEO
-of a server-rendered page. `get_next_steps` names what is waiting.
+of a page with no HTML on disk, and a list whose published row count the page cannot take (it
+renders rows no address names, or was built empty). That publish waits for its build ("Rebuilding so
+the list shows N rows") and fails with the reason if the build still shows the page's own rows: the
+site's code renders the list itself. `get_next_steps` names what is waiting.
+
+The SEO a page or entry stores is what its `<head>` says, whenever it was set: the title, the
+description, the canonical, the card fields, a `noindex` that is on. A field left empty keeps what
+the build rendered, and a site default only fills a tag the build has none of. Only a real choice
+replaces what the build renders: a meta title that merely repeats the page's name (whatever its
+case), a description that repeats the title or is the entry's auto-filled first paragraph, and
+anything on a row no person or agent has ever written (`origin` `system:*`) are read as not set. To
+change such a head, set the title or description yourself. On a route the site's app renders, no write
+reaches the head: a publish whose SEO the page does not show fails with "Published, but this page's
+code doesn't read this field yet: SEO title", and the fix is to render the head from the published
+values.
 
 Builds run `build:bcms` instead of `build` when `package.json` declares it. Keep CI-only checks out
 of it and every step the build needs in: `"build": "astro check && astro build"` beside
@@ -106,9 +120,12 @@ Identify the previous source snapshot or commit, the new one, the import manifes
 source-to-target id map and the current BetterCMS state. `list_activity` with `since` reads the
 project's durable change feed from an ISO timestamp (up to 100 events per call): call it with the
 time of the previous sync to see every dashboard or agent edit made since. Compare by stable identity, never
-by display name or row order, and confirm it is the same project and source branch. Without a
-manifest or id map this is no longer an automatic sync; treat it as a reviewed migration (the
-`bettercms-migrate` skill).
+by display name or row order, and confirm it is the same project and source branch. Entries
+written with `externalKey` (the source id) are their own id map: `list_content_entries` with
+`externalKey` finds one, and re-sending the row answers `created`, `updated` or `unchanged`
+([write-limits.md](write-limits.md)). Media, and references to items not yet created, still
+need the map. Without a manifest, keys or an id map this is no longer an automatic sync; treat
+it as a reviewed migration (the `bettercms-migrate` skill).
 
 Classify each difference and keep a three-way view where you can (the value last imported, the
 current source value, the current CMS value). Never flatten a person's CMS edit back to imported
@@ -139,7 +156,7 @@ for a content value the sync got wrong is §4.
 | Notify another system of an event | Event webhooks, `list_webhooks` / `create_webhook`: `content.publish`, `content.unpublish`, `content.stage_changed` (workflow stage), `content.created`, `content.updated`, `content.deleted` and `deployment.triggered`; HMAC-SHA256 signed in `X-BetterCMS-Signature`; payloads carry ids, never content. The signing `secret` is returned ONCE, on create. A receiver that writes back on `content.updated` loops unless it skips its own writes. Per-subscription payload filters: dashboard | You |
 | Send form submissions somewhere | Per-form integrations: Google Sheets, Slack, a webhook, email | Dashboard only |
 | Go live or retire at a time | `scheduledAt` (publish a draft at a time; needs publish permission) and `unpublishAt` (return a published row to draft) on `update_content_entry` and `update_page`; `null` cancels either. Campaigns: `publish_campaign` takes both | You. An edit that omits `scheduledAt` CANCELS the pending publish, so resend it with every edit before it fires; omitting `unpublishAt` never cancels it |
-| Load many entries | `create_content_entries`: up to 200 drafts of one collection per call, each row `created` or `failed`; then `publish_entries` | You |
+| Load many entries | `create_content_entries`: up to 200 drafts of one collection per call, each row `created` or `failed` (with `externalKey` also `updated` or `unchanged`, so a re-run is safe); then `publish_entries` | You |
 | React to edits made elsewhere | Poll `list_activity` with `since` set to the time of your last read (1–100 events per call) | You |
 | Generate or rewrite in bulk with a human gate | AI jobs: `list_ai_jobs`, `get_ai_job`, then `approve_ai_job` or `reject_ai_job` on the user's word | User approves |