@bettercms-ai/mcp 0.69.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:
@@ -55,7 +55,11 @@ build. Pass `apiUrl` and `workspace` as options, or let the snapshot supply them
 
 A section root your own code renders spreads `sectionRootAttrs(block)` from `@bettercms-ai/astro`
 (`data-bcms-block`, `data-bcms-style` and the block's style), so the editor can move it and offer
-its spacing handles ([components.md](components.md) §5).
+its spacing handles ([components.md](components.md) §5). It adds `data-bcms-hide` when `style.hideOn` is set: put `RESPONSIVE_CSS` (exported here) in your global CSS.
+
+`<BcmsBlocks>` does not render a block outside its `window`, read against the `now` prop (default:
+render time). Pass `showScheduled` on a draft preview to draw it, marked `data-bcms-window`
+([publishing.md](publishing.md) §6).
 
 `bind` and `bindProps` from `@bettercms-ai/astro/bindings` produce the same attributes as the Next
 helpers. Use them inside component instances so addresses resolve to the instance

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
@@ -207,3 +237,50 @@ still renders hard-coded copy is not connected. Client components never receive
 - `get_binding_report`'s `help.percent` is 100: every bound field also tells its editor what it
   is for. Binding a leaf makes it editable; help text makes it usable
   ([content-modeling.md](content-modeling.md), "Writing help text").
+
+## Reading the binding report and the conversion receipt
+
+`get_binding_report` per slot (`slot` is `current` or `staging`; on a promote-gated project read
+`current`, the tree the editor frames). Every figure, `unaddressable` included, is measured per
+slot. `sha` is the build the report describes; `refreshRequired` is true when that is not the
+build the slot serves. `builtRoutes` lists the routes the live build has HTML for (null = cannot
+say). `layoutIncomplete` lists Layout paths the last content apply could not write (their publish
+waits); `layoutUnread` lists Layout fields no route reads (`layoutUnreadJudged` false = not
+judged).
+
+- **Before any release** there is no report: pages 0, mode null, `refreshRequired` true.
+  `refreshReason` `never-generated` means only a release BetterCMS builds and serves writes a
+  report, so a headless site never gets one, redeploy or not; `outdated` means the next release
+  rewrites it.
+- **`unmatched` reasons**: `not-declared`, `ambiguous-text`, `no-element`, `declared-only`,
+  `needs-wrap`, `refused`, `layout-owned`, `page-owned`, `layout-locator-stale`,
+  `locale-unvarianted`, `svg-unavailable`, `partial`, `unstamped` (a page list the content apply
+  left as built; `kind` reads `list <bound>/<total>`), `mismatch` (a text-match stamp whose element
+  shows more than the value, or no longer the text it was matched on, `data-bcms-from`; never
+  written) and `report-outdated`.
+- A clean report proves each non-empty field has an element carrying its path, nothing more. A Global
+  Section counts only on the routes that render it (`layoutRoutes`).
+- **`unaddressable`** is the copy the report cannot see: visible live text no field owns, by
+  route and bucket, biggest first (null = unmeasured: diff the visible text against the entry
+  values). Over `count / visible > 0.02`, fix it in the source (wrap the run in an element the
+  codemod can bind, or declare `<BcmsField path=…>`), deploy and read again (playbook §11).
+- `canvas.lane` is the editor's live-preview lane (`bridge`, `draft-route`; `none` sends you to
+  `get_next_steps`). `coverage.error` `nothing-bound` means no element of this build is bound, so
+  its percentage describes another site.
+
+`submit_conversion_receipt` answers `complete` (`sourceComplete` is the receipt's own verdict;
+`liveChecks` gives the last release's `structureUnstamped` route count and `reportSha`) and
+`pendingTotal`, and echoes the first 40 pending rows with their `fix`:
+`{ action, file, line, col?, snippet, why?, kind? }`. `action` is one of `wrap-span`,
+`declare-attr`, `bind-expression`, `declare-richtext`, `bind-data`, `manual`; `snippet` and `why`
+say what to change. On a `declare-richtext` with `kind: document`, bind the one element wrapping
+every block of the Body, never the paragraph holding its first. A 404 `unknown-brief` means that
+digest was never issued here. The same run owes the `--forms` receipt, submitted as a second call
+under the same `briefDigest`, and the `styleEdits` of `convert --verify-styles` inside this
+receipt; one listing a changed class, className or style is refused with 409 `style-edits`.
+
+The complete brief (`get_conversion_brief { complete: true }`) also carries `forms` (id, status,
+fields, submitUrl). After the binding pass, run the codemod's forms mode (`npx
+@bettercms-ai/convert --forms`, with the brief and a receipt file) to wire them into the
+repository's own `<form>` elements. Read `forms.pending`, and publish every form `forms.notes` names in the Forms tab: a draft
+form rejects every submission with a 403.

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

@@ -25,8 +25,9 @@ Inside a section, pick the smallest shape that holds the children:
 
 - **Small identical items** (FAQ rows, feature bullets, logos): a `group` or `table` prop.
 - **One replaceable child with its own layout or variants** (a hero's media treatment): a `slot`
-  prop. It holds exactly one instance, and never sits inside a `group` or `table` row.
-- **Several different children**: the section's ordered children, not a list of slots.
+  prop. It holds one instance, and never sits inside a `group` or `table` row.
+- **Several different children**: the section's ordered children when the set is fixed; a `slot`
+  prop with `config.multiple` when the editor picks and orders them.
 
 Never let a component contain itself, directly or through a child.
 
@@ -40,8 +41,9 @@ Never let a component contain itself, directly or through a child.
    prose body and lists of object rows are sections. Read `pending` for what it will not offer:
    `NO_GROUP_ROOT` (keys are still the derive lane's own, such as `h1-welcome`: rename them into
    families first), `NOT_A_SECTION` (a lone scalar or page metadata; `detail: ENTRY_METADATA` is
-   a template's frontmatter, `detail: DECLINED` a group the user declined) and `IMAGE_AS_TEXT`
-   (a text field holding an image path; it plans once the field is an image). A nav, footer or
+   a template's frontmatter: author, images, tags and dates stay entry fields; `detail: DECLINED`
+   is a group the user declined) and `IMAGE_AS_TEXT` (a text field holding an image path; it plans
+   once the field is an image). A nav, footer or
    modal group is `NOT_A_SECTION` with `detail: LAYOUT_CHROME`: chrome is the Layout on every
    site, never a page band. Author the real sections among those with `create_component` and
    `set_page_content` instead.

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,14 +38,37 @@ 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;
-  `form` holds one Form document.
+- `select` and `multiselect` need `config.options`; `slot` holds one nested component instance,
+  or a list of them with `config.multiple`; `form` holds one Form document.
 - `slot` and `form` are reference-shaped: `target.path` is `props` (the whole envelope) on an
   empty `component` or `form` block, and their values are `{ componentId, overrides? }` and
   `{ formId }`. Neither may appear inside a `group` or `table` row.
+- **A `slot` with `config.multiple: true` holds a list.** Its value is
+  `[{ componentId, overrides? }, ...]` and its `target.path` is a container's child list:
+  `props.children` on a `section` block, or `props.columns.<n>` on a `columns` block (never
+  `props` on a `component` block). Each item is drawn there as a child component, in order.
+  Until a placement sets the slot, the children the definition holds in that list are shown;
+  `[]` shows none.
+  - `config.maxItems` defaults to 12 and cannot pass 50. `config.minItems` and
+    `config.componentIds` (which components may be listed) are checked on every write.
+  - An item may also carry `style` (use it for `hideOn`) and `window` with `from` / `until`
+    as UTC to the second (`2026-11-27T00:00:00Z`). A `defaultValue` must be an array and takes
+    no `window`.
+  - A write is a 400 whose message starts with the code: `slot_too_many`, `slot_too_few`,
+    `slot_item_invalid`, `slot_component_not_allowed`, `slot_component_unknown` (not a
+    component of this project), `component_cycle` (a component would end up inside itself,
+    through any chain), `component_too_deep` (more than 10 levels), `slot_target_invalid`,
+    `slot_not_multiple` (a list sent to a single slot). A value that is already stored is not
+    refused when the page is saved again.
+  - A child's copy is not click-to-edit on the canvas. Change it in the placement's
+    `overrides.<slot key>` list with `update_page`.
+  - Publish every listed component: a draft child renders nothing, like any draft component.
 - **A `form` prop stores an id, nothing more.** Modelling the questions again as props gives you
   two answers to "what does this form ask?", and they diverge at the first edit on either side.
   The save schema is `.strict()`, so posting the hydrated form object back is a 400, not a silent
@@ -81,6 +104,12 @@ source? } }`.
   component with a `sectionType`. A true one-off is a `section` block whose `props.children` hold
   its blocks.
 - Components that share a `sectionType` are one family: its variants.
+- **A built-in section is a starting point, not a thing you place.** `list_components` shows the
+  locked `builtin:*` blueprints; `create_component` with `from: "builtin:hero-centered"` copies
+  one into the project as an ordinary draft component, then edit and publish it like any other.
+  Whatever you send (`name`, `slug`, `props`, `blockJson`, `sectionType`, `category`) wins over
+  the copy. `list_components` `sourceKey` says which built-in a component came from. A copy
+  never follows later changes to the built-in. An unknown id is 404 `BUILTIN_NOT_FOUND`.
 - **Give every component a library `category` as well.** Why: `sectionType` groups a family, the
   category is how the component library lists it — an uncategorised component is created fine and
   is then hard to find in the picker, which is where a human looks for it.
@@ -97,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`
@@ -128,7 +158,7 @@ Handle by code, never by retrying the same call:
 |---|---|---|
 | `COMPONENT_BLUEPRINT_MATERIALIZATION_REQUIRED` | You tried to publish a platform built-in | Create a project-local component from it, publish that |
 | `COMPONENT_PROJECT_SCOPED_RELEASE_REQUIRED` | The component is workspace-global | Create a project-local variant, publish that |
-| `COMPONENT_IMPLEMENTATION_NOT_READY` | A REPO-managed component lacks exact evidence and human approval, or a variant-group member's family contract is unpublished. Never a `create_component` component outside a variant group | Report `readiness`; the owner resolves it in the dashboard |
+| `COMPONENT_IMPLEMENTATION_NOT_READY` | A REPO-managed component lacks exact evidence and human approval, or a variant-group member (the provisioned navigation and footer) has a family contract that is unpublished. Never a `create_component` component outside a variant group: that one is dashboard-managed and publishes on the preflight alone | Report `readiness`; the owner resolves it in the dashboard |
 | `COMPONENT_ORCHESTRATION_V2_REQUIRED` | The project runs implementation in Agent Dock | Continue there; stop here |
 | `COMPONENT_PUBLISH_CONFLICT` | The component or its evidence changed mid-publish | Re-read with `get_component`, then publish once more |
 | `COMPONENT_PROJECT_CONTEXT_MISMATCH` | The component's `projectId` differs from the request's project scope | Call with the component's own project |
@@ -188,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
@@ -311,4 +349,13 @@ stored list.
    siblings.
 2. `get_site_composition`: every page is sections; every component you meant to publish is
    published.
+   - Per page: `kind` is `blocks`, `fields-only` or `empty`. `nonComponentBlocks` are loose
+     top-level bands the editor's section lane cannot outline.
+   - Per placement: the component's `status` is `published`, `draft` or `missing`. `inPicker` is
+     false for a component with no `sectionType`: "Add a section" does not offer it.
+     `emptyRequiredProps` is reported only here.
+   - Site-wide: `components` counts published and draft, `awaitingEvidence` and
+     `awaitingApproval`. A person approves in the dashboard, one component at a time. Then the
+     `notInPicker` and `unused` ids, and `layout.placements`: the chrome placed in the Global
+     Layout draft.
 3. `get_binding_report` on a page that uses the component: instance values bind.

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
@@ -301,7 +305,8 @@ production cannot store it. Translate before the first write.
 | `string` | `text` with `richText: false` | `text` |
 | `text` | `longtext` | `text` |
 | `richtext` | `richtext` for section copy; `document` for the one body | `richtext` |
-| `number`, `rating` | `number` | `number` |
+| `number` | `number` | `number` |
+| `rating` | `number` with `config.min`, `max`, `step` and `ui.control: "rating"` (stars) | `number` |
 | `boolean` | `boolean` | `boolean` |
 | `slug` | `slug` (an entry's own slug stays on the entry) | `text` |
 | `url`, `link` | `link` | `link`; `url` for a media or embed address |
@@ -309,10 +314,11 @@ 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` | `array` (`itemType: "text"`); a taxonomy 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` | `text` with `richText: false` | `icon` (an icon name or an image) |
+| `icon` | `icon` (an icon name or an uploaded image) | `icon` (an icon name or an image) |
 | `button` | `button` | `button`: one prop targeting the `props` of a `button` block (§4) |
 | `reference` | `reference`; `multi-reference` for many | none: keep it on the model |
 | `code` | `longtext` | `text` |
@@ -323,12 +329,14 @@ production cannot store it. Translate before the first write.
 | `array` of objects | `repeater` | `table` |
 | `array` of strings | `array` (`itemType: "text"`) | `table` |
 | `array` of several item shapes | `modular` with `config.blockSlugs` (create the block models first) | separate components |
-| `slot` | `sections` or `component-ref` | `slot` (one instance) |
+| `slot` | `sections` or `component-ref` | `slot` (one instance; a list with `config.multiple`) |
 | a form `reference` | a `form` block inside the section | `form` |
 
-V2 features with no production shape are dropped and reported, never faked: typed table columns,
-per-breakpoint values, per-field localization, a slot with several
-children (several sections or nested components instead).
+V2 features with no production shape are dropped and reported, never faked: a per-cell table
+type, per-breakpoint values (only `style.hideOn` differs by breakpoint) and per-field
+localization. Two have a shape now: typed table columns are a `repeater` with one field per column
+and `ui.layout: "table"`, and a slot with several children is a `slot` prop with `config.multiple`
+([components.md](components.md) §1).
 
 | The plan says | Production word |
 |---|---|