@bettercms-ai/mcp 0.70.0 → 0.72.0

package/dist/skills/bettercms/SKILL.md

@@ -59,7 +59,10 @@ These hold on every task. The reference in brackets has the detail and the codes
    beside a link field. [components.md, content-modeling.md]
 4. **Nothing is live until it is published, and a page is not its content.** A draft form,
    component or entry renders nothing live. Read `warnings` on every write: `ENTRY_STILL_DRAFT`
-   and `ENTRY_SEED_FAILED` mean content did not ship. [publishing.md]
+   and `ENTRY_SEED_FAILED` mean content did not ship. An answer that leads with `held`, and a
+   publish reading `outcome.status: "partial"`, did not reach the site: do the action it names
+   before you report it.
+   [publishing.md]
 5. **Name the folder system every time you say "folder"**: Content sidebar folders never touch a
    URL, URL page folders are part of the path, media folders organise assets.
    [content-modeling.md]
@@ -126,8 +129,9 @@ resources: `bettercms://skill/bettercms` for this file, and each reference under
 | Components, props, variants, component publish codes | [components.md](references/components.md) | creating, swapping, publishing or validating a component | component, prop, variant, sectionType, publish component |
 | One section, source HTML to bound template: hero, feature grid, pricing table, testimonials, FAQ | [worked-examples.md](references/worked-examples.md) | you want the whole path for one section in production shapes | example, hero, pricing, FAQ, testimonial, source to schema |
 | 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 |
+| 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, BcmsSections, --sections |
 | 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 |
@@ -139,7 +143,7 @@ resources: `bettercms://skill/bettercms` for this file, and each reference under
 | SEO and AEO | [seo.md](references/seo.md) | meta, JSON-LD, sitemap, robots, redirects, AI crawlers, `list_seo_issues` | SEO, meta, JSON-LD, schema.org, sitemap, robots, OG image, redirect, 410, llms.txt |
 | Accessibility: alt text, form labels, contrast, the audit codes and the manual checks | [accessibility.md](references/accessibility.md) | writing alt text; building a form; before reporting a site done | accessibility, WCAG, alt text, decorative, label, contrast, captions |
 | Page families from data | [programmatic-seo.md](references/programmatic-seo.md) | a keyword list or CSV should become pages | programmatic SEO, CSV, dataset, landing pages, glossary |
-| Publish, deploy, roll back, reconcile a re-import | [publishing.md](references/publishing.md) | a release; a code push that conflicts with CMS edits | publish, deploy, rollback, sync, webhook, schedule, automation |
+| Publish, deploy, roll back, reconcile a re-import; add a section to a page or set its spacing | [publishing.md](references/publishing.md) | a release; a code push that conflicts with CMS edits; "add a section here", "more padding on this section"; a write that answers `held` or a publish that reads `partial` | publish, deploy, rollback, sync, webhook, schedule, automation, add section, insertSection, sectionStyle, spacing, padding, margin, held, partial |
 | Read-only launch review | [site-review.md](references/site-review.md) | "is this ready to launch?" without fixing | launch review, audit, is it ready, QA |
 | A/B tests on section variants | [content-experiments.md](references/content-experiments.md) | an experiment plan or readout | A/B test, experiment, variant test |
 | Headless Shopify storefront | [shopify-headless.md](references/shopify-headless.md) | Shopify owns commerce, BetterCMS the editorial | Shopify, Hydrogen, storefront, product |
@@ -181,7 +185,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`, run
+   `receipt.gate.nextAction` and read again after each batch; nothing else ends an imported
+   site's setup, and an exception is recorded only for a reason that is true. 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,251 @@
+---
+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
+
+The bound element picks the writer. One that holds text and nothing else is replaced whole, as
+it always was. One that holds markup (inline elements, split spans, a `<br>`, or
+`data-bcms-split`) is written into its text nodes, and every element inside it is kept. 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 split headline under an `aria-label` that says the same words (SplitText's own output) | one field on the headline: writes the label and the words |
+| A counter with its number in `data-target`, `data-count` or a like attribute | writes the attribute; writes the number shown only where it showed the old target, never a script's starting `0` |
+| 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.
+
+The last two rows follow a value only where the element was written into its text nodes. An
+operator can switch a project, or the fleet, to write every text value that way, so a plain-text
+value's copies and props follow it too; and can switch the text-node writer off, after which a
+publish replaces an element's content with plain text and refuses what that would break.
+
+## 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.
+
+`<BcmsSections>` follows the same rule for a whole section: the block id, the style marker and
+the block's style go on the section's own root, and in Astro the list is delimited by two HTML
+comments, never an element. `main > section`, `:first-child` and a ScrollTrigger on `.hero` match
+what they matched before. The one exception is a section that is not one element (several roots,
+an island, in Next a component child with no function form): it gets a box of ours, a node
+between `main` and the section. With no style on the block the box is `display:contents` and
+draws nothing. Once the block has a style the box is `display:flow-root` and carries it: one
+block box, so in a flex or grid parent its children are one item instead of several, and their
+margins stop collapsing with the neighbours'. Give such a section one root element, or the
+function form ([next.md](next.md)), when a selector or the layout depends on it.
+
+## 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

@@ -40,9 +40,10 @@ build. Pass `apiUrl` and `workspace` as options, or let the snapshot supply them
 | Import | Use |
 |---|---|
 | `@bettercms-ai/astro/components/BcmsBlocks.astro` | Server render of a block tree. Pass `components` or instances render nothing |
+| `@bettercms-ai/astro/components/BcmsSections.astro` | The page's own sections as named slots, drawn in the CMS page's order (below) |
 | `@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:
@@ -51,6 +52,48 @@ build. Pass `apiUrl` and `workspace` as options, or let the snapshot supply them
 - Its CSS class names differ from `BcmsBlocks`. Swapping one for the other unstyles a page unless
   your stylesheet covers both spellings.
 
+## Sections in the CMS order
+
+A page whose sections are written in its `.astro` file follows the CMS page's block list through
+`<BcmsSections>`. `bettercms init` writes this wrap (`npx @bettercms-ai/convert --sections`);
+write it by hand for a page the codemod refused ([componentize.md](componentize.md) §5):
+
+```astro
+---
+import BcmsSections from "@bettercms-ai/astro/components/BcmsSections.astro";
+---
+<Layout>
+  <BcmsSections page="home">
+    <Fragment slot="hero"><Hero title={title} /></Fragment>
+    <Fragment slot="code:sec1"><LogoStrip /></Fragment>
+    <Fragment slot="pricing">{plans.length > 0 && <Pricing plans={plans} />}</Fragment>
+  </BcmsSections>
+</Layout>
+```
+
+- `page` is the CMS page's slug. Each section is one `<Fragment slot="…">` around markup you do
+  not change. Anything with its own `slot="…"` (it targets the layout) stays outside.
+- A slot is named by its placement's bind: the family of the section's first bound field
+  (`pricing-title` → `pricing`), which is the `bind` on the page's `component` block.
+- A block bound to a slot renders it at the block's position. `data-bcms-block`, `data-bcms-style`
+  and the block's style go on the section's own root element; no element is added, so the stamp
+  never comes between a parent and a child a selector or an animation names
+  ([animation.md](animation.md) §10). A slot that renders several roots, or an island, is stamped
+  on a box: `display:contents` while its block has no style, one `display:flow-root` box once it
+  has. Give it one root element where the layout must not gain a box.
+- A section added in the editor (a block with no bind) is drawn by `BcmsBlocks`, which
+  `BcmsSections` imports itself: nothing to pass, and it builds whether or not `bettercms()` is
+  registered on that build (a config that adds it only with credentials still draws the section).
+- A slot no block names: `code:<bind>` always renders where it is written. A bare `<bind>` does
+  too until the list names one of the page's slots; from then on it is a removed section. Write
+  a slot bare only when the page already places that bind (`get_page`), otherwise `code:`.
+- No snapshot (a local build, the API down): every slot renders in source order, untouched.
+- The list is the published snapshot's, or the draft's when the Visual Editor frames a
+  server-rendered page (`prerender = false`). `blocks={…}` gives it yourself.
+
+Check: build, then view source. `<!--bcms-sections:start page="home"-->` precedes the sections,
+and each placed section's root carries `data-bcms-block` and `data-bcms-style`.
+
 ## Bindings
 
 A section root your own code renders spreads `sectionRootAttrs(block)` from `@bettercms-ai/astro`
@@ -72,5 +115,7 @@ helpers. Use them inside component instances so addresses resolve to the instanc
 | Resized images 404 on a non-production site | `mediaUrl` still the production default | Set `PUBLIC_BCMS_MEDIA_URL` to that rung's API origin |
 | Resized images still on the CDN after moving media | `mediaUrl` not changed | Set it to `mediaBaseUrl` from `get_project` |
 | Component instances empty | `components` prop missing | Pass definitions to `BcmsBlocks` |
+| A code section vanished after a build | Its slot is bare and the page's block list does not place its bind | Name it `code:<bind>`, or place the bind on the page |
+| Build fails on `bettercms:config` | A page imports `BcmsSearch` or the virtual module on a build where `bettercms()` is not registered | Register it unconditionally. `BcmsSections`, `BcmsBlocks`, `BcmsImage` and `BcmsForm` need no integration |
 | Draft link 500 | `BCMS_DRAFT_SECRET` unset | Set it on the server env, redeploy |
 | `ReferenceError: X is not defined` from a `[slug].astro` route | `getStaticPaths()` reads a `const` declared in the frontmatter; Astro runs it in its own scope, before the page, seeing only imports | Declare the client or reader call inside `getStaticPaths`, or import it from a module |

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
@@ -64,7 +68,19 @@ value over everything else inside it, so:
   `button` field rendered with `BcmsButton` ([components.md](components.md)).
 - **SVG text is never bound; the icon is.** No field is derived from the text inside an `<svg>`,
   and no binding there is measured. Each inline icon IS an editable `image` field (`config.media:
-  "icon"`, an svg value): an editor swaps it. Never remove one to tidy a form; group it.
+  "icon"`, an svg value): an editor swaps it. Never remove one to tidy a form; group it. So is a
+  sprite icon (`<svg><use href="#id">`) whose `<symbol>` is in the same page, a wordmark set in
+  `<text>`, and an illustration up to 64 KB. A swap keeps the element's classes and size and
+  stays inline, so `currentColor` still applies; scripts and remote references are stripped.
+- **Copy in an attribute is a field of its own.** Every release derives a text field for an
+  `aria-label`, a `title`, a `placeholder` outside a form, and the number a count-up script
+  counts to (`data-target`, `data-count`, `data-value` and their kin). Its `config.attr` names the
+  attribute; it is bound on `data-bcms-props` as `<path>|text|<attribute>` and published into that
+  attribute alone, never matched against the page's words. A label that only repeats the words
+  on its own element gets none. To declare one in code, write the same `data-bcms-props` entry.
+- **Text beside an icon in a plain element** (`<span>Pages<svg/></span>`) is a field when it is
+  the element's one text node: the save writes that node and leaves the icon. Split over several
+  text nodes it stays `BARE_TEXT`, so wrap the label in its own `<span>` where you can.
 - **Icon-only links in the nav and footer** take their field name from what a screen reader
   reads: the anchor's `aria-label`, its `sr-only` text, a `title`, the SVG `<title>` or an `alt`
   (never `<style>` or `<script>` text). Give each one an `aria-label` or `sr-only` label, or every
@@ -92,6 +108,31 @@ 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`, and everything else it declines in `elementGaps`
+([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 +144,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/componentize.md

@@ -46,7 +46,10 @@ Never let a component contain itself, directly or through a child.
    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.
+   `set_page_content` instead. The other codes need no decision: `ALREADY_COMPONENTIZED` (a
+   placement exists), `EMPTY_GROUP` (no field holds a value), `NESTED_REPEATER` (a repeater three
+   deep; two levels become a nested `table` sub-field) and `PAGE_NOT_EMPTY` (the page holds
+   blocks this lane does not own, and it will not overwrite them).
 2. Show the user the sections, how many components it creates and which pages it rewrites.
    Confirm before writing. A group the user says is not a section: `componentize_sections
    { digest, sections: [groupKey], pageIds, decline: true }` (`decline: false` undoes it). The
@@ -56,9 +59,11 @@ Never let a component contain itself, directly or through a child.
    again and confirm again. Then run it for real.
 4. What it writes: each component as a DRAFT, and each page's draft blocks as an ordered list of
    instances. By default each instance carries `props.bind` and the words stay in the page's
-   field group, so bindings and the coverage meter do not move. `copy: "instance"` moves the
-   words onto each placement and marks the old fields `origin: "componentized"`; nothing is
-   deleted. Running it twice is safe: an existing placement comes back as
+   field group, so bindings and the coverage meter do not move. `copy: "instance"` is the
+   page-builder model: each placement takes its group's CURRENT draft values into its own
+   `props.overrides` (a repeater becomes one `table` prop holding every row), records the page
+   path each came from in `props.source`, and drops `props.bind`. The old fields are kept and
+   marked `origin: "componentized"`; nothing is deleted. Running it twice is safe: an existing placement comes back as
    `ALREADY_COMPONENTIZED`.
 5. `publish_component` for each, then publish the pages. An unpublished component renders
    nothing on the live site.
@@ -67,7 +72,8 @@ Never let a component contain itself, directly or through a child.
    commit to). In a checkout, run the codemod with `--componentize` and a `--receipt` file, commit
    and push the files it wrote, and hand that receipt verbatim to `submit_componentize_receipt`. It records
    each extracted section as the source of the component with the same slug, so no
-   `set_component_source` per component is needed. Deploy.
+   `set_component_source` per component is needed. Deploy. A page whose bands could not be
+   lifted is wrapped where it stands instead (§5).
 7. Output validation, from step 3 of §6.
 
 ## 3. Names and groups
@@ -75,7 +81,10 @@ Never let a component contain itself, directly or through a child.
 Name a family by what it is (`Hero`, `CTA`, `Testimonials`) and each variant by how it looks
 (`Hero / Split`, `CTA / Centered`). Never put a page name in a reusable definition; which pages
 use it is a usage question (§8). The componentize lane files a section under its page's slug
-(`home-hero`) but keeps the name the section's own (`Hero`). Keep related fields together in the
+(`home-hero`) but keeps the name the section's own (`Hero`). Its components go into the Component
+Group you pass as `group` (a folder of the dashboard's Components tab), else into one named for
+the section family: nav, header, footer or menu into Layout, an unnamed section into Sections,
+any other into the family's own name (Hero, FAQ). Keep related fields together in the
 order an editor reads them:
 
 ```text
@@ -111,3 +120,53 @@ and after publish:
 - one chrome edit reaches every route.
 
 Then `get_binding_report` and `get_site_composition` (§9).
+
+## 5. The page wrap (`--sections`): sections that stay in the site's code
+
+Lifting a band into a component (§2) needs an inline run and a plan. A page built from imported
+section components with props has neither, and it does not need them: `--sections` wraps the
+page's top-level sections in `<BcmsSections>`, one named slot each, so the site's own build draws
+them in the CMS page's order, with each block's spacing and style, and draws a section added in
+the editor between them. It changes no section's markup, props, classes or styles.
+
+`bettercms init` runs it before the agent starts and commits it locally
+(`chore(bettercms): render sections from BetterCMS`); the dispatch of step 6 runs it after
+`--componentize`. Do not redo or revert that commit. Pushing it is the user's decision. To run
+it yourself, in a clean checkout:
+
+```sh
+npx @bettercms-ai/convert --sections --root . --dry-run   # the plan, per page
+npx @bettercms-ai/convert --sections --root .
+npx @bettercms-ai/convert --verify-styles --root .        # must report no style edits
+```
+
+A page it leaves alone keeps rendering as before, and is listed with one of these:
+
+| Reason | The page | What you do |
+|---|---|---|
+| `SECTION_RUN_NOT_FOUND` | Returns markup from several places, or has loose text between sections | Give it one root, wrap loose text in an element, run again; or write the wrap by hand |
+| `SECTION_RUN_NOT_CONTIGUOUS` | A child with `slot="…"`, a `<script>` or a `<style>` sits between two sections | Move it above or below the sections, run again |
+| `SECTIONS_IN_LAYOUT` | Gives its layout no children: the layout draws the sections | Move the sections into the page, or wrap them by hand in the layout for that one page |
+| `SECTION_RUN_DYNAMIC` | A `[slug]` route no collection page has for its item template (a parameter above the last segment, or no collection at that path) | Nothing: its sections stay in code. A collection's own `[slug]` file is wrapped once, for the collection page, and every entry draws that list |
+| `CLIENT_COMPONENT` | A `"use client"` page that exports more than the page | Move those exports to a server file and run it again. Any other client page is wrapped: it moves into `page.client.tsx` and its page file becomes the server parent that reads the order |
+| `PAGE_PROPS_IN_USE` | Pages Router page on `getInitialProps`, a data function it only re-exports, or a rest parameter | Add `bcmsSections` to its props by hand ([next.md](next.md)) |
+| `PAGE_UNKNOWN` | No CMS page for the route | Create and publish the page, run again |
+| `DIALECT_UNSUPPORTED` | Markdown, MDX or HTML | Nothing: the body is one `document` field |
+| `NAME_TAKEN` | Already uses the name `BcmsSections` for something else | Rename that, run again |
+| `SDK_REQUIRED` | The repo's SDK predates the component | Add `--add-sdk`, install, run again |
+
+The by-hand markup is in [astro.md](astro.md) and [next.md](next.md), and it follows the rules of
+[animation.md](animation.md) §10: slot tags around sections you do not edit, no new element. On
+a wrapped page two notes ask for a hand edit. `ROOT_IS_COMPONENT` (Next): the section moves and
+takes its spacing on a box around it, which is one block box once styled; write its child as a
+function and spread the root props on the component's root element to style the root itself.
+`EXPRESSION`: a `.map()` or a conditional is ONE section; to move its rows separately, give each
+row its own slot.
+
+Slots are written `code:<bind>` unless the page already places that bind; a `code:` slot is
+never removed by the list. After the page's placements exist, run `--sections` again (or
+`bettercms init`): it writes those slots bare, and from then on removing the block removes the
+section. Any other framework gets `FRAMEWORK_UNSUPPORTED` and no write.
+
+Check: after the build, the route's row in `get_binding_report` reads `stamped` equal to `placed`
+and `ordered: true`.