@bettercms-ai/mcp 0.70.0 → 0.71.0

package/dist/skills/bettercms/SKILL.md

@@ -128,6 +128,7 @@ resources: `bettercms://skill/bettercms` for this file, and each reference under
 | The same for an article entry, navigation in the Global Layout, tabs holding columns | [worked-examples-advanced.md](references/worked-examples-advanced.md) | a collection entry with a body, site chrome, or nested blocks | example, blog post, document body, mega menu, tabs, columns |
 | Componentize a derived site | [componentize.md](references/componentize.md) | `get_site_composition` shows pages made of fields only | componentize, sections, fields-only, get_componentize_plan |
 | Click-to-edit attributes, addresses, declared mode | [bindings.md](references/bindings.md) | `grep -rl "data-bcms-" src` finds files; a value the editor cannot select | data-bcms-field, click to edit, binding report, stega, declared |
+| Animated sites: GSAP, ScrollTrigger, split text, Framer Motion, Lenis, marquees, carousels, Lottie, hydrated islands | [animation.md](references/animation.md) | `package.json` lists `gsap`, `lenis`, `framer-motion`, `swiper` or a text splitter; a publish refused with `SPLIT_PATTERN_UNKNOWN` or `ISLAND_PROPS_UNMATCHED`; a `client-only-island` gate exception | animation, GSAP, ScrollTrigger, SplitText, Lenis, Framer Motion, marquee, Swiper, Lottie, island, client:only, data-bcms-split |
 | Wiring, env, hosting modes, media host, snapshots | [frameworks.md](references/frameworks.md) | `package.json` lists an adapter; `bcms-content.json` exists | hosting, headless, env, codegen, types, revalidate, snapshot |
 | Astro adapter | [astro.md](references/astro.md) | the repo has `astro.config.*` | astro.config, Astro, BcmsBlocks, getStaticPaths |
 | Next.js adapter | [next.md](references/next.md) | the repo has `next.config.*` | next.config, Next.js, App Router, ISR, notFound, static export |
@@ -181,7 +182,12 @@ Stop at the first step that is not clean, fix, then restart. A report that does
 3. `get_site_composition`: every page you touched is made of sections, with the intended
    components.
 4. `list_seo_issues`: no issue on a page you created or edited.
-5. `get_next_steps`: nothing left that belongs to your task; owner actions go in your final
-   message by name.
-
-"Done" means the loop is clean, not that a tool call returned 200.
+5. `get_next_steps`: `receipt.complete` is `true`. While it is `false`, take the first row of
+   `receipt.gate.blocking`, run its `fix`, and read again; nothing else ends an imported site's
+   setup. The gate, its bars and the exceptions it accepts are in
+   [finish-site.md](references/finish-site.md). Suggestions still in `missing` after that, and
+   owner actions, go in your final message by name.
+
+"Done" means the loop is clean and the gate reads complete, not that a tool call returned 200.
+`bettercms init` reads the gate again when you exit and prints its numbers per page, so the
+user sees them whatever your last message said.

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

@@ -0,0 +1,235 @@
+---
+title: "Animated sites"
+description: "Keeping GSAP, ScrollTrigger, SplitText, Framer Motion, Lenis, marquees, carousels, Lottie and hydrated islands working while their copy stays editable and publishable."
+---
+
+# Animated sites: editable copy that keeps moving
+
+Read this when `package.json` lists `gsap`, `lenis`, `framer-motion` or `motion`, `swiper`,
+`split-type`, `splitting`, `lottie-web` or `three`, or when the built HTML carries
+`astro-island`, split-text spans or a duplicated marquee track. Attribute grammar:
+[bindings.md](bindings.md). Adapter wiring: [frameworks.md](frameworks.md).
+
+## 1. What a publish does to animated markup
+
+A text publish on a project in the text-node mode (off by default, for new projects too: the
+operator switches it on per project, or for the fleet) writes the change into the element's
+text nodes and keeps every element inside it. That is what the recipes below rely on:
+
+| The page has | A publish does |
+|---|---|
+| Inline markup inside the bound element (`<em>`, a highlight `<span>`, `<br>`) | changes the words, keeps the elements and their attributes; a bare `<em>` or `<span>` the new words leave empty is removed |
+| Text cut into `word` / `char` / `line` spans, same word count | writes each span in place |
+| The same, word count changed, spans made by a library at runtime | puts the plain text back; the library splits it on its next run |
+| The same, spans written by your own template | rebuilds them from their own pattern, a new one copied from the last |
+| A copy of the value under `aria-hidden="true"` or `data-bcms-clone` | writes the copy too (coverage kind `duplicate-track`) |
+| The value inside `astro-island` props, `__NEXT_DATA__` or the app router's flight scripts | rewrites the serialized string (coverage kind `island-props`) |
+
+It refuses, and says so on the publish, when the change would have to remove something:
+`TEXT_IN_CHILD_FIELD` (the words belong to a field declared inside this one),
+`TEXT_EMPTIES_ELEMENT` (a link, a scripted element or a wrapper with attributes would be left empty),
+`SPLIT_PATTERN_UNKNOWN` (split markup that is not one row of like tokens) and
+`ISLAND_PROPS_UNMATCHED` (a hydrated island draws the text from props that do not hold it).
+Each is fixed in the template with the recipe for its library.
+
+On a project in the older mode, the default, a text publish replaces the element's content with
+plain text. There, bind only elements that hold text and nothing else.
+
+## 2. Two rules for every library
+
+1. **Bind the element that holds the words, never the element the animation owns.** A pinned
+   section, a scroll wrapper, a slider track and a motion container are layout. Their text
+   leaves are the fields.
+2. **Refresh measurements after an edit.** The editor posts `{ type: "bcms:content-applied" }`
+   to the page's window after it applies an edit. Longer copy changes heights, so anything that
+   measured the page must measure again:
+
+```js
+window.addEventListener("message", (event) => {
+  if (event.data?.type !== "bcms:content-applied") return;
+  ScrollTrigger.refresh();   // or lenis.resize(), swiper.update(), split.revert() then split again
+});
+```
+
+`onContentApplied(handler)` from `@bettercms-ai/sdk` is the same listener with the check
+written for you. On a published page nothing posts the message and the listener never runs.
+
+## 3. GSAP and ScrollTrigger
+
+```html
+<section class="pin-wrap">                      <!-- trigger and pin: no field -->
+  <div class="pin">
+    <h2 data-bcms-field="story.title">Built to last</h2>
+    <p data-bcms-field="story.lead">Forged, not cast.</p>
+  </div>
+</section>
+```
+
+```js
+gsap.to(".pin h2", { yPercent: -20, scrollTrigger: { trigger: ".pin-wrap", pin: ".pin", scrub: 1 } });
+```
+
+Never put `data-bcms-field` on `.pin-wrap` or `.pin`: ScrollTrigger wraps a pinned element in
+a spacer and writes inline styles on it every frame. Use `<BcmsField>` only around a single
+element, where it adds no wrapper (section 10); a wrapper span between `.pin` and its `h2`
+would break `.pin > h2`.
+
+Check: with the page open, `ScrollTrigger.getAll().length` is the same before and after a
+publish of every field on the route.
+
+## 4. SplitText, SplitType, Splitting.js
+
+Bind the parent and say that it is split. Never bind a word or a character.
+
+```html
+<h1 class="js-split" data-bcms-field="hero.title" data-bcms-split="words">Fast screws, shipped</h1>
+```
+
+```js
+let split = new SplitText(".js-split", { type: "words" });
+window.addEventListener("message", (event) => {
+  if (event.data?.type !== "bcms:content-applied") return;
+  split.revert();
+  split = new SplitText(".js-split", { type: "words" });
+});
+```
+
+`data-bcms-split` takes `chars`, `words` or `lines`. It tells the editor that the spans under
+this element are one value, and it tells a publish that the children are tokens even when their
+class is not `word`, `char` or `line`.
+
+When your own template writes the spans (`title.split(" ").map(...)`), keep them one row of
+the same tag, with whitespace or nothing between them, and no other element in the row:
+
+```astro
+<h1 data-bcms-field="hero.title" data-bcms-split="words">
+  {title.split(" ").map((word) => <span class="word">{word}</span>)}
+</h1>
+```
+
+A `<br>` between two word spans makes the row unreadable once the word count changes
+(`SPLIT_PATTERN_UNKNOWN`): put the break in CSS, or split by lines.
+
+Check: publish a title with one more word, reload, and count `.word`: it equals the new word
+count and no word sits outside a span.
+
+## 5. Framer Motion
+
+```tsx
+<motion.section initial={{ opacity: 0 }} whileInView={{ opacity: 1 }}>   {/* no field */}
+  <motion.h2 data-bcms-field="story.title" variants={rise}>{story.title}</motion.h2>
+  <p data-bcms-field="story.lead">{story.lead}</p>
+</motion.section>
+```
+
+Put `data-bcms-field` straight on the motion element that renders the text: it passes
+`data-*` through to the DOM. Do not wrap a motion component in `<BcmsField>`; a component child
+keeps the wrapper span, and `layout` animations measure the wrong box. For words animated one
+by one, map them to `motion.span` under a parent carrying `data-bcms-split="words"`, as in
+section 4. The component hydrates, so section 9 applies to its props.
+
+Check: the built HTML for the route shows `data-bcms-field` on the `h2` itself, with no
+`display:contents` span around it.
+
+## 6. Lenis and other smooth scroll
+
+Lenis moves the page, not the content, so no binding changes. Two things do:
+
+```js
+const lenis = new Lenis();
+window.addEventListener("message", (event) => {
+  if (event.data?.type === "bcms:content-applied") lenis.resize();
+});
+```
+
+and any panel of yours that must scroll by itself inside the page takes `data-lenis-prevent`.
+Never bind the element Lenis is given as `wrapper` or `content`.
+
+Check: after an edit that adds two lines to a paragraph, the page still scrolls to the footer.
+
+## 7. Marquees and duplicated tracks
+
+Render the track once with fields, and mark every copy:
+
+```astro
+<div class="marquee">
+  <ul class="track">{logos.map((l, i) => <li class="logo" data-bcms-field={`logos[${i}].name`}>{l.name}</li>)}</ul>
+  <ul class="track" aria-hidden="true" data-bcms-clone>{logos.map((l) => <li class="logo">{l.name}</li>)}</ul>
+</div>
+```
+
+A copy under `aria-hidden="true"` or `data-bcms-clone` is not counted as unowned text, and a
+publish writes it with the original when it is the same tag with the same classes and the same
+text. A copy with neither marker is separate copy: it counts against the route's text coverage
+and keeps the old words. A script that clones the track in the browser needs nothing: the clone
+is made from the published HTML on every load.
+
+Check: publish one logo name, then `document.querySelectorAll(".track")` shows the new name in
+every track.
+
+## 8. Swiper and carousels
+
+Bind what is inside a slide, never `.swiper-wrapper` or `.swiper-slide`:
+
+```html
+<div class="swiper-slide"><h3 data-bcms-field="slides[0].title">Torque</h3></div>
+```
+
+Loop mode clones slides in the browser (`.swiper-slide-duplicate`); those are made from the
+published HTML and need no field. On `bcms:content-applied`, call `swiper.update()`.
+
+Check: `get_binding_report` lists no `slides[n]` path as pending for the route.
+
+## 9. Hydrated islands and `client:only`
+
+A hydrated component draws itself again from the props the build serialized. Keep the text it
+shows equal to one string prop, whole:
+
+```astro
+<Hero client:load title={page.hero.title} />
+```
+
+```tsx
+export default function Hero({ title }) { return <h1 data-bcms-field="hero.title">{title}</h1>; }
+```
+
+A publish then rewrites that prop with the text. It cannot when the component builds the text
+(`${title}!`, `title.toUpperCase()`, a string literal in the component), or when the props hold
+the same words more than once, under a key such as `id` or `slug`, or as `__html`: the publish reports
+`ISLAND_PROPS_UNMATCHED` and the value goes live with the next build. Content passed as a
+slot is plain HTML and needs no prop.
+
+`client:only` renders nothing at build time, so the built page has no copy to own. The release
+names every such island on its route and the setup gate lists it as a `client-only-island`
+exception by itself. To make the copy editable, change the directive to `client:load` or
+`client:visible`, or pass the copy in as a slot.
+
+Check: view source on the built route, find the `astro-island`, and its `props` attribute holds
+the published title after a publish.
+
+## 10. `<BcmsField>` adds no wrapper around one element
+
+```astro
+<BcmsField path="hero.title"><h1 class="title">{page.hero.title}</h1></BcmsField>
+```
+
+renders `<h1 class="title" data-bcms-field="hero.title">`: nothing sits between the parent and
+the heading. Text, several children, and in Next a component child are still wrapped in a
+`display:contents` span, and `as="div"` still gives a real wrapper. A site built with an older
+package version keeps its wrapper spans until it is rebuilt.
+
+## 11. Lottie, canvas, WebGL, video
+
+Pixels drawn by a script are not in the HTML, so nothing in them is a field by itself. What is
+editable is what you pass in:
+
+| Drawn by | Make editable by |
+|---|---|
+| Lottie | Bind the animation file as an image-or-file field on the container and load `path` from it. For words inside the animation, keep a text layer named after the field and set it at load (`anim.renderer.elements[i].updateDocumentData({ t: value })`), reading the value from a hidden bound element or a prop. |
+| Canvas / WebGL / three.js | Read every string and texture URL from `data-*` attributes or props on the canvas's container; bind a visually hidden element per string and an `<img hidden>` per texture, and re-read them on `bcms:content-applied`. |
+| Video | The poster and the source are fields on the `<video>`; burned-in captions are not text. |
+
+Give the canvas `role="img"` and an `aria-label` bound to a field, or an adjacent caption. A
+scene with no text a visitor reads needs no field; record it under the `decorative` exception.
+
+Check: change the bound string, publish, reload: the drawn text reads the new value.

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

@@ -41,8 +41,8 @@ build. Pass `apiUrl` and `workspace` as options, or let the snapshot supply them
 |---|---|
 | `@bettercms-ai/astro/components/BcmsBlocks.astro` | Server render of a block tree. Pass `components` or instances render nothing |
 | `@bettercms-ai/astro/components/BcmsLiveBlocks.astro` | Same tree as a hydrated island that follows the editor's draft bridge |
-| `@bettercms-ai/astro/components/BcmsField.astro` | `path`, `kind` (`richtext`/`image`), `as`; emits `data-bcms-field` + `data-bcms-kind` |
-| `@bettercms-ai/astro/components/BcmsButton.astro` | A `button` field: `path`, `value`, `class`. One `<a>` with the label bound, the href in `data-bcms-props` and `data-variant` / `data-size` for your CSS; renders nothing without a label |
+| `@bettercms-ai/astro/components/BcmsField.astro` | `path`, `kind` (`richtext`/`image`), `as`; emits `data-bcms-field` + `data-bcms-kind` on its single child element, with no wrapper ([animation.md](animation.md) §10) |
+| `@bettercms-ai/astro/components/BcmsButton.astro` | A `button` field: `path`, `value`, `class`. One `<a>` with the label bound, the href in `data-bcms-props` and `data-variant` / `data-size`. Style only the looks the site has ([components.md](components.md) §5); renders nothing without a label |
 | `@bettercms-ai/astro/components/BcmsForm.astro` | Renders a delivered form and submits it ([forms-and-interactions.md](forms-and-interactions.md)) |
 
 `BcmsLiveBlocks` rules:

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

@@ -20,8 +20,12 @@ cannot resolve an address guesses, which works once.
 
 **Put the attributes on the element that renders the value and nothing else: the `<img>` itself,
 the `<h1>` itself. Never a wrapper, never an element whose children you need.** A declared write
-replaces what is inside the element it names. Bind a `<section>` or a card and the band's own
-markup is what you overwrite; the page comes back as bare text where a layout used to be.
+owns what is inside the element it names. Bind a `<section>` or a card and the band's own
+markup is what a rich text or image write overwrites; the page comes back as bare text where a
+layout used to be. A plain-text write keeps the inline elements inside its element (a highlight
+`<span>`, split-text spans, a `<br>`) on a project in the text-node publish mode, and replaces
+them on an older one: [animation.md](animation.md) §1 has both, and the recipe per animation
+library.
 
 `data-bcms-kind` does not choose the editor; the MODEL does. The attribute says **"this element is
 the declared CONTAINER for the field"**, so the canvas repaints it whole. Leave it off and the
@@ -92,6 +96,30 @@ the fallback; the build renders it and the publish writes the editor's image. Fr
 images are in the Media Library, matched by file name. An image rendered inside a loop over a
 list is not bound automatically: bind it in the list's data file.
 
+The codemod knows an image component by its IMPORT, not its name: `Image` and `Picture` from
+`astro:assets` (aliased, or through `import * as assets`), and the default export of
+`next/image` under any name. An import that reaches the page through `getImage()`, `hero.src` or
+a style is refused as `IMAGE_ASSET_UNRESOLVED`, and the row's message names the import: declare
+the element that shows it by hand (`data-bcms-field` + `data-bcms-kind="image"`).
+
+Images need no code at all on a text-matched site. Every release derives an image field for each
+picture a page shows: an `<img>` (its `src`, or where that is a placeholder a lazy loader's
+`data-src`, then the largest `srcset` candidate), a whole `<picture>` as ONE field, a
+`<video poster>`, an inline or STYLESHEET `background-image` (Tailwind `bg-[url(...)]` included)
+and an inline `<svg>`. What it declines is listed with a reason in the binding report's
+`imageGaps` ([media-and-brand.md](media-and-brand.md) Where images hide).
+
+Publishing an image keeps the page responsive. A library image re-points every `srcset`
+candidate and each `<source>` at the new picture at that candidate's own width and format, and
+leaves `sizes`, `width`, `loading`, classes, ids and `data-*` as written; never hand-edit those
+after a swap. A stylesheet background gets one inline `background-image` over the rule, removed
+again when the value returns to the sheet's own picture.
+
+To keep an image editable in code you write yourself, render it with `BcmsImage` and its `path`
+(Astro: `@bettercms-ai/astro/components/BcmsImage.astro`; Next: `BcmsImage` from
+`@bettercms-ai/next`): one `<img>` that declares the field, reads the value's alt, crop and focal
+point, and offers a width ladder when given `sizes`.
+
 ## 3. Addresses
 
 The grammar is identical in `@bettercms-ai/next` and `@bettercms-ai/astro`; emit it with the SDK
@@ -103,7 +131,9 @@ helpers rather than by hand.
   this list. An `href`, an `src` and a `poster` are kind `url` (`cta.href|url|href`, not
   `|text|`); an `alt` is `text`. The same address on two elements is edited as two copies of one
   value (numbered `data-node-index`).
-- `<BcmsField path kind as>` wraps hand-rendered entry values. `path` is dotted keys with any
+- `<BcmsField path kind as>` binds hand-rendered entry values. Around ONE element it adds no
+  wrapper: the attributes go on that element. Around text or several elements it renders a
+  `display:contents` span, and `as` names a real wrapper. `path` is dotted keys with any
   number of `[n]` indices: `title`, `hero.title`, `columns[0].links[2].href`.
 - Rich text is addressed per paragraph: `<base>#<_key>`. No write tool takes an address:
   `update_content_entry` replaces the whole field (with `merge: true` it keeps the other

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

@@ -23,9 +23,9 @@ reference is what the code does with what you write. Componentizing a derived si
 A component declares `props`. Each prop is `{ key, label, type, target: { blockId, path },
 defaultValue? }`.
 
-- `type` is one of exactly 18: `text`, `richtext`, `image`, `url`, `boolean`, `number`,
-  `select`, `group`, `table`, `slot`, `form`, then `date`, `color`, `file`, `link`, `icon`,
-  `multiselect` and `button`.
+- `type` is one of exactly 30: `text`, `richtext`, `image`, `url`, `boolean`, `number`, `select`, `group`, `table`, `slot`,
+  `form`, then `date`, `color`, `file`, `link`, `icon`, `multiselect` and `button`, then `object`, `datetime`, `slug`,
+  `email`, `phone`, `json`, `location`, `tags`, `rating`, `code`, `reference` and `multi-reference`.
 - The last seven store what the same-named model field stores: `date` is `YYYY-MM-DD`, `color` a
   hex, `file` `{ url, name?, size? }`, `link` an href string or `{ href, rel?, newTab? }`, `icon` an icon name or an image
   value, `multiselect` a `string[]` drawn from `config.options`. A bad `defaultValue` is a 400.
@@ -38,7 +38,10 @@ defaultValue? }`.
 - Every prop takes `helpText` and the component a `description` ("Hero with a heading,
   supporting text and two buttons."). Leave them out and the platform writes them; write your
   own by the rules in [content-modeling.md](content-modeling.md) ("Writing help text").
-- A prop takes `showIf` (`{ match, rules: [{ field, op, value? }] }`): hidden until SIBLING props match. `op` is `eq`, `neq`, `in` or `isSet` (no `value`); model fields take the same four.
+- A prop takes `showIf` (`{ match, rules: [{ field, op, value? }] }`): hidden until SIBLING props match. `op` is `eq`, `neq`, `in`, `isSet`, `notEmpty` or `empty`; the last three take no `value`, the first three need one. Props and model fields share all six, and a sub-field's `showIf` names its sibling sub-fields.
+- `object` holds ONE `{ childKey: value }` built from `config.fields` (required), like the model field `object`. Groups, tables and objects nest to 10 levels counting the prop; an 11th is refused `field_depth_exceeded`. Aim an `object` at `props` or at a key your component code reads, never at a text slot such as a heading's `props.text` (`prop_target_unrenderable`).
+- `datetime`, `slug`, `email`, `phone`, `json`, `location` (`{ lat, lng }`), `tags` (`string[]`), `rating` (0..`config.max`) and `code` (`{ language?, code }` or a string) hold what the same-named model field holds, and a placement's value is checked by that field's rules (`prop_value_invalid`). Like `object`, a `tags` or `code` prop never targets a text slot.
+- `reference` holds one CMS item's id and `multi-reference` a list of them, as the model fields do: `config.contentModelId`, or `polymorphic: true` with `allowedModelSlugs` (one of the two is required), and `min`/`max` on the list. A placement's new id must exist (`REF_MISSING`); an id already stored is never re-checked. Page reads (delivery, preview) hydrate the ids to entries at their `depth`, so component code reads the entry; on a heading or button text slot the entry's title renders. A `multi-reference` never targets a text slot.
 - `update_component` replaces the whole `props` array. Read with `get_component`, change, write
   all props back.
 - `select` and `multiselect` need `config.options`; `slot` holds one nested component instance,
@@ -123,8 +126,9 @@ source? } }`.
   Default, Featured and Outline is ONE component with a `select` prop keyed `variant` whose options
   are the looks, and its markup picks classes from that value. Why: an editor switches the look in
   place and the content stays put, and the library holds one card, not three. Families of looks
-  (`variantOf`, a style select on every section that places them) are for buttons: a new button
-  look is `get_component`, then `create_component` with `variantOf` naming the base.
+  (`variantOf`, a style select on every section that places them) are for buttons. On a site
+  built in BetterCMS a new button look is `get_component`, then `create_component` with
+  `variantOf` naming the base. On an imported site the family is read, not written (§5).
 - Read `warnings` and act on them; they never block the write:
   - `create_component` / `update_component`: `VARIANT_PROP_KEYS_MISMATCH` (a key no sibling
     declares, or one siblings declare that this variant lacks) and `VARIANT_PROP_TYPE_MISMATCH`
@@ -214,8 +218,16 @@ A code-built site ships only what its templates draw, whatever the page's `block
   the repo root (`--dry-run` first); give each root it reports as skipped (`OWN_STYLE`, `SPREAD`,
   `BLOCK_ID_ONLY`, …) its block style by hand, confirm with `--verify-styles`, push and release.
 - **A `button` field renders with `BcmsButton`** (`path`, `value`): one `<a data-bcms-button>`
-  carrying `data-variant` and `data-size`, so the site's CSS decides what each look looks like and
-  every look control (style, size, arrow, icon, new tab) applies on the canvas and on publish.
+  carrying `data-variant` and `data-size`, so every look control (style, size, arrow, icon, new
+  tab) applies on the canvas and on publish.
+- **A button's looks are the ones the site already has.** Each release measures the built pages
+  and keeps the project's Button family equal to the looks found there, named as the site names
+  them (`btn-outline` is Outline). Style offers those looks and no others, and a publish paints a
+  pick with the site's own classes. Never write CSS for a look so that a control "works": there
+  is no fixed list of variants to implement. A `button` value's `variant` is one of those looks;
+  a refused value comes back with the looks the project has. A look the site drops is flagged,
+  never deleted. A new look is the owner's design decision: add its class to the site, then
+  Rebuild.
   Without the SDK, write that same anchor: `data-bcms-button="<path>"`, the label in its own
   `<span data-bcms-field="<path>.label">`, the href through `data-bcms-props`. The arrow is the
   `svg.bcms-btn-arrow` it draws; never leave a hand-written arrow `<svg>` beside it, or turning

package/dist/skills/bettercms/references/content-modeling.md

@@ -46,7 +46,11 @@ collection: the model and its entries both point at the page (`content_models.pa
 A listing elsewhere (latest posts on home, related posts on an article) is a `collection` block
 with `source: { modelId }`, never copied entries. It also takes `filters` (max 5, `{ field, op,
 value }` with the content API operators), `sort` (`-publishedAt,title`), `pinnedIds` (max 10,
-shown first), `excludeCurrent` and `limit`. BetterCMS-rendered pages read it on every request;
+shown first), `excludeCurrent` and `limit` (default 20), beside `order` (`newest` or `oldest`) and
+`emptyText`. `cardComponentId` names the component each card is drawn through; without one a card
+shows the entry's `titleField` (default `title`) and `excerptField`. On a `dynamic` page the block
+lists that page's collection and draws ONE entry on `/<page>/<entrySlug>`, through
+`detailComponentId` when set. BetterCMS-rendered pages read it on every request;
 a route the repo builds does not draw this block, so list there with the content API.
 
 | Source pattern | BetterCMS destination |
@@ -126,7 +130,7 @@ sitemap), RSS (dated by `publishedAt`), `llms.txt` (one link per published item)
 - **Lists are arrays; tags are taxonomy.** Features, steps, benefits and "what's included" are an
   `array` (`itemType: "text"`), or a repeater when each item carries its own state (included or
   not, an icon). Never a group holding one field. A label set that filters or classifies entries
-  is a shared collection referenced with `multi-reference` (§2), not free text.
+  is a `tags` field; when each label has its own page, a collection referenced with `multi-reference` (§2).
 - **Never freeze a feed.** A list of entries on the source stays a listing: copying the nine
   visible cards into a repeater stops it updating. On a page BetterCMS renders, that is the
   `collection` block: on the collection's own dynamic page it lists that collection, and with
@@ -310,7 +314,8 @@ production cannot store it. Translate before the first write.
 | `date`, `datetime` | `date`, `datetime` | `date` (`YYYY-MM-DD`); a datetime stays `text` |
 | `color` | `color` | `color` |
 | `select` | `select` | `select` with `config.options` |
-| `multiselect`, `tags` | `multiselect` with `config.options` (a `string[]`; `config.allowCustom` for free tags, `min`/`max` count the choices); a taxonomy with its own pages is a collection plus `multi-reference` | `multiselect` with `config.options` |
+| `multiselect` | `multiselect` with `config.options` (a closed `string[]` choice list; `min`/`max` count the choices) | `multiselect` with `config.options` |
+| `tags` | `tags` (a `string[]`; `config.options` are suggestions, `allowCustom: false` closes the list); a taxonomy with its own pages is a collection plus `multi-reference` | `tags` |
 | `image` | `image` | `image` |
 | `file`, `video` | `file`; a hosted video URL is a `link` | `file`; `url` for a hosted video |
 | `icon` | `icon` (an icon name or an uploaded image) | `icon` (an icon name or an image) |

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

@@ -49,7 +49,7 @@ a product). One page cannot tell chrome from content.
 |---|---|---|
 | 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 |
+| `<astro-island>`, `__NEXT_DATA__`, `window.__NUXT__` | Hydrated islands | Parse the HTML, then render to read the islands. Their inline JSON often holds the data. Binding their copy: [animation.md](animation.md) §9 |
 
 When you render:
 
@@ -139,7 +139,7 @@ match when the sequence is equal and optional parts are missing only at the ends
 | Siblings of different kinds in one grid (a card, a quote, a big number) | The section's ordered children. When the editor picks and orders them, a `slot` prop with `config.multiple`; a plain `slot` holds ONE instance |
 | 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
+Count content levels, not DOM nodes. Component props nest at most ten levels, counting the prop; a deeper subtree
 becomes its own component, placed as a child.
 
 **Collections.** A set of records with one shape and their own URLs.

package/dist/skills/bettercms/references/finish-site.md

@@ -31,8 +31,86 @@ answers `complete: true` (no path left in `paths.pending`), and after the deploy
 `declared`. A build job works from `bettercms://playbook/schema` (the `build_site` prompt carries
 the same flow on a local MCP) and is done when the site is deployed, `get_component_readiness`
 is clean for every component it placed, and `get_next_steps` lists nothing left to do from code.
-Both end in the verify loop of SKILL.md. One converted page, or a receipt with paths still
-pending, is not a finished site; report the numbers, not an impression.
+Both end in the verify loop of SKILL.md, and an imported site ends only on the setup gate below.
+One converted page, or a receipt with paths still pending, is not a finished site.
+
+## The setup gate: what "finished" is measured by
+
+`get_next_steps` returns `receipt.complete` and `receipt.gate`. The platform computes the gate
+from the last release, one verdict per route of the live build. The CLI that launched you reads
+it again when you exit and prints it to the user, so the gate is the report, not your summary.
+While the gate is incomplete that command exits 3 (0 once it is complete; 2 is a wrong command
+line), which is what a script waiting on the setup reads.
+
+| Check | Passes when | Where it shows |
+|---|---|---|
+| `page` | a CMS page, or a collection entry, serves the route | `routes.rows[].page` |
+| `published` | that page, and its entry, is published | `routes.rows[].page` |
+| `twin` | no second page claims the same route | `blocking.rows` |
+| `text` | 2% or less of the visible characters sit outside a field | `routes.rows[].text` |
+| `image` | each image a visitor sees belongs to a field, and the release named no picture it could not make one | `routes.rows[].image`, `imageGaps` |
+| `link` | 95% of the links have a field for the label or the destination | `routes.rows[].link` |
+
+`pages` counts routes built, created and published. `coverage` sums `editable` of `total` across
+the site. `routes.rows` is ordered worst first, with `failing` per route and the reasons the
+deriver `skipped` copy there. `blocking.rows` is the work list: each row carries a `detail` with
+its number and a `fix`, the single call to run next. Run the first `fix`, call `get_next_steps`,
+repeat until `complete`. A `fix` of `null` means no tool closes that row (a collection's listing
+route, a URL that cannot be placed, two pages nobody but the owner can choose between): put it to
+the user and stop retrying. Treat a row that its fix did not move the same way.
+
+A `page` row on a route setup left without a page carries the pages lane's reason in its
+`detail` (`invalid-path`, `html-too-large`, `page-deleted`, `slug-taken`, `folder-conflict`,
+`entry-not-registered`, `authored-content` and the rest), with what closes it: a change in the
+site's code, another page to move, or the user's decision. Only `unreadable`, `write-failed`
+and `not-registered` carry a `fix`. An `image` row with a `null` fix names a picture by its code
+([media-and-brand.md](media-and-brand.md) Where images hide): the change is in the site's code.
+`imageGaps` also lists the decoration the import declined, which blocks nothing. On a
+collection's listing route the rows that link to its entries are counted as the collection's,
+so the listing page is judged on its own heading, intro and calls to action.
+
+### Exceptions go on the record
+
+A check you are leaving on purpose is recorded, one row per route and check, with
+`editor_setup` and `exempt: [{ route, check, reason, note }]`. `note` states what is being left
+in a sentence a person can verify. `reason: null` withdraws one.
+
+| `reason` | May excuse |
+|---|---|
+| `form-validation-copy` | `text` |
+| `legal-boilerplate` | `text` |
+| `third-party-widget` | `text`, `image`, `link` |
+| `decorative` | `text`, `image` |
+| `duplicate-track` | `text`, `image`, `link` (the cloned track of a marquee or slider) |
+| `client-only-island` | nothing: it lists an island the build cannot show, and the route still meets the bar outside it |
+| `user-declined` | every check except `twin`, and only with the user's own words quoted in `note` (`User: "leave pricing in code"`) |
+
+A row excuses what its check read when it was recorded. When the route reads differently
+later (more copy nobody owns, another picture), the row stops counting and the check blocks
+again: record it again if it still stands. The CLI prints every `user-declined` row marked for
+the user to confirm.
+
+Refused whatever the note says: `out-of-time`, `out-of-context`, `too-many-routes`,
+`tool-failed`, `not-asked`, `good-enough`. A sentence to the user about a gap is not an
+exception either: the gate stays incomplete, and the CLI exits non-zero with that gap listed.
+
+### What setup derives on a collection's item pages
+
+Setup reads a few entry pages of each collection and makes one field of everything they render
+at the same place: text, each image (an `<img>` with only a `srcset`, a `<picture>`, a
+background its stylesheet paints), a call to action (one `button`, or a label and its `-href`
+where the project derives pairs), a plain list, and a gallery or spec table as a repeater whose
+rows each entry fills from its own page. The article's container becomes the place the entry's
+`body` is read from and bound, so `body` holds the article alone. An element the site's code
+already declares keeps its declaration and gets no second field. A collection from before this
+gains the fields add-only; its `body` is bound only while no entry of it was edited. Check the
+result per entry route in the gate, never by adding the same fields by hand.
+
+Copy the template shows unchanged on every entry (a "Related posts" heading, an "Add to cart"
+button) is one field marked `config.shared`, and its value lives on that field, once: no entry
+holds it. Edit it as a field of any one entry and publish that entry: the value moves onto the
+field and every item page is repainted. Until then it is that entry's draft, shown on no page.
+A translated entry keeps its own words for it. Never write the same value into each entry.
 
 Git belongs to the owner. Verification releases go out from the working tree, so the job never
 needs a commit to prove itself. After the final report, ask whether they want the changes

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

@@ -72,7 +72,8 @@ H1. Expose typography variants only where the design allows a real choice.
   not in each page.
 - **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
+  `srcset`/`sizes`, poster, lazy/preload intent and art direction (a publish keeps them too:
+  [bindings.md](bindings.md) Images). Decorative images render an
   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`
@@ -112,6 +113,26 @@ H1. Expose typography variants only where the design allows a real choice.
   every video into the media library by default; keep a streaming provider reference where the
   site depends on one.
 
+## Where images hide
+
+Setup makes every picture an image field backed by a library asset, in code, with no step for
+you: the release adopts each media file the build ships (alt text from the markup, its size, and
+a default focal point you can move with `update_media`), derives the fields, and links each
+value to its asset. Check it, never redo it: the binding report's `elementCoverage.image` is
+`editable / total`, and `imageGaps` names what is not a field, misses first.
+
+| Code | The picture | What to do |
+|---|---|---|
+| `IMG_DATA_URI`, `IMG_NO_SOURCE` | An `<img>` inlined as `data:`, or filled in by a script | Ship it as a file with a real `src` |
+| `BG_PSEUDO_ELEMENT` | A background on `::before` / `::after` | Move it onto the element, or render an `<img>` |
+| `BG_ON_TEXT` | A background on an element that is itself a text field | Wrap the text, so the box and the words are two elements |
+| `SVG_TOO_LARGE` | An inline `<svg>` illustration past the icon size | Ship it as an `.svg` file in an `<img>` |
+| `SVG_SPRITE`, `SVG_NOT_ICON`, `SVG_DECORATIVE` | A `<use>` sprite, a chart, a nameless glyph | Decoration: leave it, or give a logo `role="img"` and an `aria-label` |
+| `BG_SPRITE`, `BG_TINY`, `BG_PATTERN`, `BG_DATA_URI`, `BG_STATE` | A sprite, an icon-sized box, a tile, an inlined texture, a hover image | Decoration: leave it |
+
+The first four rows count against the image coverage; the last two do not. A gap you cannot
+close is reported with its code, never described as done.
+
 ## Media host
 
 Use `mediaBaseUrl` from `get_project`: media is served from the CDN origin or the API origin of

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

@@ -40,14 +40,15 @@ webhook. Use the project's webhook secret from the dashboard (the package docs n
 |---|---|
 | `BcmsBlocks` | Render a block tree; pass `components` from `readComponents()`. A block outside its `window` is not rendered, read against `now` (default: render time); `showScheduled` draws it marked `data-bcms-window`, for a draft preview |
 | `readComponents()` | Component definitions from `bcms-content.json` |
-| `BcmsField` | `path`, `kind` (`richtext`/`image`), `as`; server-safe |
-| `BcmsButton` | A `button` field: `path`, `value`, `className`; one `<a>` with `data-variant` / `data-size` for your CSS; server-safe |
+| `BcmsField` | `path`, `kind` (`richtext`/`image`), `as`; server-safe; no wrapper around a single DOM element ([animation.md](animation.md) §10) |
+| `BcmsButton` | A `button` field: `path`, `value`, `className`; one `<a>` with `data-variant` / `data-size`. Style only the looks the site has ([components.md](components.md) §5); server-safe |
 | `sectionRootAttrs(block)` | Spread on a section root your own code renders: `data-bcms-block`, `data-bcms-style` and the block's style, plus `data-bcms-hide` when `style.hideOn` is set: ship `RESPONSIVE_CSS` (exported here) in your global CSS ([components.md](components.md) §5) |
 | `bind`, `bindProps` | Binding attributes; instance-aware inside components |
 | `BcmsForm` + `getForm(idOrName)` | Forms from the snapshot ([forms-and-interactions.md](forms-and-interactions.md)) |
 | `buildMetadata(page, siteDefaults, location?)` | Next `Metadata` from native SEO fields |
 | `llmsTxtRoute(config)` | An `llms.txt` route handler |
-| `imageUrlBuilder({ baseUrl })` | Resize URLs. No `BcmsImage` in Next; same media-host rules as Astro |
+| `imageUrlBuilder({ baseUrl })` | Resize URLs; same media-host rules as Astro |
+| `BcmsImage` | An image field as one `<img>`: `path`, `src` (the value), `sizes` or `width`; declares the field and keeps the value's alt, crop and focal point; server-safe |
 
 Rules: