@bettercms-ai/mcp 0.71.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,7 +129,7 @@ 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 |
@@ -140,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 |
@@ -182,9 +185,9 @@ 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`: `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
+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.
 

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

@@ -12,9 +12,10 @@ Read this when `package.json` lists `gsap`, `lenis`, `framer-motion` or `motion`
 
 ## 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 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 |
 |---|---|
@@ -22,6 +23,8 @@ text nodes and keeps every element inside it. That is what the recipes below rel
 | 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`) |
 
@@ -32,8 +35,10 @@ It refuses, and says so on the publish, when the change would have to remove som
 `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.
+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
 
@@ -218,6 +223,17 @@ the heading. Text, several children, and in Next a component child are still wra
 `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

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

@@ -40,6 +40,7 @@ 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` 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 |
@@ -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

@@ -68,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
@@ -107,7 +119,8 @@ picture a page shows: an `<img>` (its `src`, or where that is a placeholder a la
 `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).
+`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

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`.

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

@@ -192,16 +192,24 @@ component.
 
 ### When the site's own code renders the sections
 
-A code-built site ships only what its templates draw, whatever the page's `blockJson` says.
+A code-built site ships only what its templates draw, whatever the page's `blockJson` says. The
+setup gate judges it per route (`sections` and `style`, [finish-site.md](finish-site.md)), and
+adding or spacing one section is the recipe in [publishing.md](publishing.md).
 
 - **Render the page's block list, never hard-coded bands.** A section added or moved in the
   editor reaches the live site only when the template loops over the page's blocks in order and
-  each section root carries its block id as `data-bcms-block`. The codemod's `--componentize` pass
-  generates `src/lib/bcms-sections.ts` for the loop and adds those attributes. Until it ships, the
+  each section root carries its block id as `data-bcms-block`. The codemod writes both: `--sections`
+  wraps a page as it is (below), and `--componentize` lifts its bands into components and
+  generates `src/lib/bcms-sections.ts` for the loop. Until one ships, the
   editor still adds, moves, swaps and removes sections (saved, and drawn on the canvas at once),
   tells the author that publishing leaves the live order to the site's code, and its "Let BetterCMS
   control section order" button commits that same codemod to the connected repository. `submit_conversion_receipt` keeps
   `complete: false` with one `SECTIONS_UNSTAMPED` row per route.
+- **A page of imported section components is wrapped, not lifted.** `<BcmsSections>` takes each
+  top-level section as a named slot and draws the block list in order, stamping each section's
+  own root; a section added in the editor renders between them. `bettercms init` writes and
+  commits the wrap; what it refused, and the markup to write by hand, is in
+  [componentize.md](componentize.md) §5.
 - **The order is measured, not assumed.** A release reads the stamped section roots in document order:
   a build that draws them in the CMS order (`ordered: true` on the binding report's structure row)
   owns nothing, whatever sections it has no code for; one that draws them in its own order
@@ -221,13 +229,32 @@ A code-built site ships only what its templates draw, whatever the page's `block
   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.
+  and keeps the project's Button family equal to the looks found there. 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.
+- **Each look is named for the role it plays on that site, and a site has only the roles it
+  uses.** One site's family is Primary, Secondary, Tertiary; another's is Primary, Secondary,
+  Ghost, Outline, Text Link. Never create, rename toward, or ask for a role the site does not
+  use, and never number one ("Outline 2"): the release gives the names, in this order.
+
+  | Role | The look that gets it |
+  |---|---|
+  | The site's own name | A look the site names keeps that name: `btn-primary` is Primary, `btn-ghost` is Ghost, `data-variant="link"` is Text Link. Its stored `variant` value stays the site's own. |
+  | Primary | Exactly one: the filled look used most (placements, then pages, then hero placements). On a site that fills nothing, its most used outline or ghost. |
+  | Brand | The most used look filled with a colour, when Primary is a neutral dark or light fill, or when the site names a less used look Primary. |
+  | Secondary | The look most often beside Primary in a button group; else the next most used look that is not a text link. |
+  | Tertiary | A third filled look. Further fills are Dark, Light, or the colour's name. |
+  | Outline | Bordered and not filled. |
+  | Ghost | No fill and no border, padded like a button or filled on hover. |
+  | Text Link | A plain link the site styles as a call to action. Menu and footer links and links in copy are not looks. |
+
+  A light and a dark rendition, a hover or disabled state, a size, and one paint spelled in two
+  sets of classes are all ONE look. Two looks left with one role are told apart in words from
+  their paint ("Outline on dark", "Pill Outline"). A role once given stays: a look added later
+  takes a role that is free and renames nothing, and a name a person gave is never changed back.
   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

@@ -179,7 +179,12 @@ fail, because the next redesign makes them lie.
 
 Short labels named for what the editor sees: Heading, Body, Primary button, Label, Link, Image,
 Alt text — or the name the site's code already uses (`cents` → Cents), never the copy itself
-(`.00`). Most fields need no help line from you (below). Group by what renders
+(`.00`). An import names every field it derives the same way, by its section and its role
+there: "Hero headline", "Hero intro", "Hero primary button", "Pricing plans", "Footer link 2
+URL", "Header logo"; a list's columns by their role in the row ("Title", "Description", "Link
+URL"). A role is numbered only where it repeats in one section, and labels are unique on a page.
+Keys never change. Rename a label where the site's code has a better word: a name you give is
+kept on every later release, and one the import gave follows the import. Most fields need no help line from you (below). Group by what renders
 together, not by the DOM or the source file: core content first, optional appearance second, technical fields hidden. Repeatable items need a meaningful preview label (the FAQ question, the
 button label), reorder, and stable item ids. An empty optional field removes its element without
 leaving a gap; a long value wraps, and clamps only where the design intends it.

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

@@ -9,6 +9,13 @@ description: "Take an imported or converted site to fully editable: the gap ledg
 verified with evidence. "Fully editable" is a measured result, never an inference from imported
 schemas. New to the project, or no repo on disk yet: [getting-started.md](getting-started.md).
 
+## Contents
+
+- [Inputs and baseline](#inputs-and-baseline) · [The finish line for a convert or build job](#the-finish-line-for-a-convert-or-build-job)
+- [The setup gate: what "finished" is measured by](#the-setup-gate-what-finished-is-measured-by)
+- [The gap ledger](#the-gap-ledger-bettercmsledgerjson) · [Repair order](#repair-order-and-the-reference-for-each-step)
+- [Proof loop](#proof-loop) · [Launch decision](#launch-decision)
+
 ## Inputs and baseline
 
 Require the project, source repository or import snapshot, site URL, import manifest, hosting
@@ -50,15 +57,100 @@ line), which is what a script waiting on the setup reads.
 | `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` |
+| `sections` | every section the page places is a stamped root on the built page, none twice, none published after the build, and a section added in BetterCMS has somewhere to show (`accepts` `list` or `in-place`) | `routes.rows[].sections`: `accepts`, `renderer` (`sdk`, `registry`, `annotator`), and when it fails `refusal` (why the release cannot write the page) and `wrap` (`wrapped`, or `refused:<REASON>` from the sections conversion) |
+| `style` | every stamped section root carries the style marker (`data-bcms-style`, or `data-bcms-block-style` on a root that is a field's element) or is drawn by the route's block renderer, counted by setup on the served page, so a block's spacing, padding and background paint | `routes.rows[].style` |
+| `svg` | every inline SVG a visitor sees (a logo, an icon, an illustration) belongs to a field; a hidden symbol sheet is not counted | `routes.rows[].svg` |
+| `number` | every element whose whole text is a number (a stat, a price, a rating) belongs to a field | `routes.rows[].number` |
+| `attribute` | every `alt`, `aria-label`, `title` and `placeholder` with words in it belongs to a field | `routes.rows[].attribute` |
+| `names` | no field of the page, and no component, has a name a person cannot read: a slug, a hash, a structural word (`Section 2`, `wrap`), or a number beside the same name (`Icon 2`) | `blocking.rows` |
+| `seo` | the page has a title of at most 70 characters and a description of at most 200, and a canonical where the build ships one for this site's origin; site-wide, every page has a share image, its own or the site's default | `blocking.rows` |
+| `structuredData` | JSON-LD the build ships on the route is on the page or the entry | `blocking.rows` |
+| `collections` | sibling routes that are one family (three under one parent, or two under `tags`, `category`, `author`) are a collection; reported on the family's listing route, built or not | `blocking.rows` |
+| `buttons` | every button field is one of the site's live Button looks, the Button family is the looks setup measured on this build (the same looks, not the same count), and no look is named by a number or a build's class | `blocking.rows`, `route: null` |
+| `components` | the authoring question is answered, and no section is left that a componentize run would place | `blocking.rows`, `route: null` |
+| `forms` | every form of the customer's has an address to notify; a form setup ignored (sign-in, add to basket) is not counted | `blocking.rows`, `route: null` |
 
 `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
+the site, `svg`, `number` and `attribute` included, and `open` counts the rows still open per
+check. `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
+its number, a `fixCode` and a `fix`, the call that closes it.
+
+`nextAction` is the one thing to do now: the fix a tool can make that closes the most rows
+(`fixCode`, `count`, the `fix` of its first row, the first `routes`), two with the same count in a
+fixed order. Run it on every row that carries that `fixCode`, call `get_next_steps`, and repeat
+until `complete`: following it reaches `complete` with no step that changes nothing. A fix no
+tool can make is named only when nothing else is left. 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 `sections` or `style` row is a page nobody can add a section to, reorder or space, however
+complete its copy is. Its `fixCode` names the one fix, and `fix` the call when a tool can make it:
+
+| `fixCode` | The fix |
+|---|---|
+| `run-sections-conversion` | Only the site's code can draw this page's sections: its app renders the route, a framework hydrates the page whole (`PAGE_HYDRATED`), or the release could not map its bands. In a checkout run `npx @bettercms-ai/convert@latest --sections --root .` ([componentize.md](componentize.md) §5), or call `componentize_sections` with `codemod: true` and the plan's `digest`; `--upgrade-sections` for a `style` row. Then push and release |
+| `rebuild` | The build that serves is older than what makes the row pass: a published section, the wrap's commit (`wrap: "wrapped"` on a row that still fails), or the in-place switch. No tool starts one: ask the user to push and Rebuild |
+| `enable-in-place-structure` | A static page the release can write by itself, and the project's in-place structure switch is off. Setup switches it on for a project it creates; on an existing one it is the operator's call. No repository change |
+| `run-setup` | Nothing measured what the row reads, or a page is still to register: `editor_setup { force: true }`, then read again |
+
+The other rows name their fix the same way:
+
+| `fixCode` | The fix |
+|---|---|
+| `bind-elements` | `get_conversion_brief { complete: true }` lists what no field owns on the route; bind each (an SVG as an image or icon field, a number as its own field, attribute copy with `data-bcms-props`) |
+| `rename-fields` | `get_page`, then `update_field` with a name a person would say; `update_component` for a component |
+| `fill-seo` | `update_page` with `metaTitle` and `metaDescription` (`update_content_entry` with `meta` for an entry; `generate_seo_meta` drafts one from text you give it); a missing canonical is setup's to copy from the built head, so that row carries `editor_setup { force: true }`; the site-wide row wants the site's default share image, `update_seo` with `seoDefaults.ogImage` |
+| `import-structured-data` | `editor_setup { force: true }` imports the build's JSON-LD; `update_seo` when it has to be written by hand |
+| `model-collection` | `create_content_model` with the family's `urlPattern` (`/tags/:slug`), then its entries: one item template for the family ([content-modeling.md](content-modeling.md)) |
+| `derive-buttons` | `editor_setup { force: true }` mints a Button for each look the build draws, retires one it no longer draws and maps each button to its look; rename a look with `update_component` ([components.md](components.md)) |
+| `componentize` | `set_authoring_preference` when nobody answered, then `get_componentize_plan` and `componentize_sections` ([componentize.md](componentize.md)) |
+| `set-form-recipient` | ask the user where the form's submissions go, then `update_form` with `notifyEmails`; `update_form { ignored: true }` when it is not one of their forms |
+
+A row nothing measured reads `unmeasured: true` with `run-setup`, and `gate.unmeasured` lists the
+checks that have one: a release older than a count, or a project set up before setup recorded
+what it found on the build (the style marker of each section root, the looks it measured, the
+canonicals the build ships). It is not a failure of the site and not a pass either: run
+`editor_setup { force: true }` once and read again.
+
+Setup closes what is deterministic by itself, on every run, so your first receipt is already past
+it and an open row of these means run setup again: `run-setup`, `derive-buttons` (the family and
+the map), `import-structured-data`, `fill-seo` from the built head and the page's own copy,
+`rename-fields` for a field still carrying a derived name, `componentize` once the authoring
+answer is `components`, and `enable-in-place-structure` on a project it creates. What is left
+takes judgement and is yours: `bind-elements`, `model-collection`, `set-form-recipient` (ask the
+user), `run-sections-conversion`, a name a person gave, a title over its limit, a look named by a
+number, and the authoring answer itself (the user's). `rebuild` is the user's.
+
+Beside the gate, `data` lists what else is unfinished, each item by its `ruleId`: content
+(`mcp-pages-draft`, `mcp-pages-missing-meta`, `mcp-model-empty`, `mcp-form-no-recipient`,
+`mcp-pending-review`), bindings and structure (`conversion-pending`, `bindings-not-declared`,
+`unaddressable-copy`, `upgrade-section-roots`, `upgrade-element-styles`, `componentize-pages`,
+`components-unpublished`), the authoring answer (`authoring-undecided`), the Layout lane
+(`layout-write-blocked`, `layout-field-unread`, `layout-locator-stale`, `layout-rebuild-required`,
+`layout-unpublished`, `chrome-duplicated`), publishes (`publish-held`) and the Content sidebar
+(`organise-content`). `setup-gate` is first while the gate is open and `publish-held` next.
+
+Stamps are not enough to pass either check: the lane that serves a route must have PROVED it.
+Each release adds a probe section to the middle of one built page of each kind (a page, a
+listing, an item template) and a probe padding to one of its sections, in memory, finds both in
+the result and takes them out again; the sections conversion proves each page it wraps the same
+way. `routes.rows[].proof` is that record (`lane`, `route`, `insert`, `style`: `ok` or the
+reason). A row whose proof was never run asks for it where it runs: `editor_setup { force: true }`
+for the release, the conversion again for a wrapped page. `SLOTS_NOT_PLACED` on a wrapped page
+means every slot is still `code:`: place the page's sections, then run the conversion again.
+
+The gate picks the fix per route, in that order of evidence: a wrapped page waits for its build; a
+page a script draws needs the conversion; a static page needs only the switch. Run the fix the
+row names and no other: the conversion does nothing for a row that says `rebuild`.
+
+Two rows have no `fixCode`. A page that places a section twice: remove the second placement with
+`update_page`. A route neither lane serves: the release cannot write it (`refusal`) and the
+conversion refused it (`wrap`); its `detail` names both. Put it to the user: write the wrap by
+hand ([astro.md](astro.md), [next.md](next.md)) or change the page. No exception covers it
+(`document-body` excuses only a route that places no section). Check a route's row again after
+each release; never mark one done from the codemod's own output.
+
 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
@@ -67,7 +159,17 @@ and `not-registered` carry a `fix`. An `image` row with a `null` fix names a pic
 ([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.
+so the listing page is judged on its own heading, intro and calls to action, and on the words
+of a row the release bound to its entry (a field's there too). The release binds
+each such row to its entry: the row carries `data-bcms-entry`, a part showing a field as stored
+carries `data-bcms-entry-field` (`entry:<id>:<path>`, written when that entry publishes), and a
+part the site's code made from a field (a cut excerpt, a reformatted date or price, a thumbnail,
+the item link) carries `data-bcms-entry-from` with the transform, read-only: edit the entry.
+Never add a field for a row to the listing page. A taxonomy's term routes (`/tags/<term>`, each
+listing another collection's entries) are a small collection of terms, and their rows are bound
+the same way. A term has a `body` only where its template has an article. Chrome the Layout
+could not take (an icon with no Media asset) is template copy on item routes: one shared field
+of the collection, as it is a page's own field on a page.
 
 ### Exceptions go on the record
 
@@ -79,11 +181,16 @@ in a sentence a person can verify. `reason: null` withdraws one.
 |---|---|
 | `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) |
+| `third-party-widget` | `text`, `image`, `link`, `svg`, `number`, `attribute` |
+| `decorative` | `text`, `image`, `svg` |
+| `duplicate-track` | `text`, `image`, `link`, `svg`, `number`, `attribute` (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"`) |
+| `user-declined` | `page`, `published`, `text`, `image`, `link`, `svg`, `number`, `attribute`, `seo`, `structuredData`, `collections`, and only with the user's own words quoted in `note` (`User: "leave pricing in code"`) |
+| `document-body` | `sections`, and only on a route that places no section at all: a page that is one document (a markdown post, a legal page) |
+
+Nothing else excuses `sections`, and nothing excuses `style`, `twin`, `names`, `buttons`,
+`components` or `forms`: not the user's decision either. A name is fixed by renaming, and a form
+that is not the customer's is marked ignored.
 
 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
@@ -149,7 +256,7 @@ and add the new result. Update the file as each row moves, so a reset loses at m
 |---|---|---|
 | 0 | Editor setup: `editor_setup { check: true }` reads `ready` for the live build (run `editor_setup` when it does not) | [getting-started.md](getting-started.md) |
 | 1 | Routing and data shape: page / collection / entry classification and folders; keep public URLs | [content-modeling.md](content-modeling.md) |
-| 2 | Sections and reuse: every band a section; dedupe compatible patterns into variants and overrides; nav and footer as globals (`get_componentize_plan`, `componentize_sections` on a components project) | [components.md](components.md), [componentize.md](componentize.md) |
+| 2 | Sections and reuse: every band a section; dedupe compatible patterns into variants and overrides; nav and footer as globals (`get_componentize_plan`, `componentize_sections` on a components project). `bettercms init` has already wrapped each page's sections in `<BcmsSections>` and committed it: fix only the pages it refused ([componentize.md](componentize.md) §5) | [components.md](components.md), [componentize.md](componentize.md) |
 | 3 | Editor contract: field types, labels, help text on every element (`get_next_steps` shows no `help-text-missing`), validation, Portable Text accept lists, nested groups | [portable-text.md](portable-text.md) |
 | 4 | Design: media, logo roles, fonts and brand tokens, without changing visual intent | [media-and-brand.md](media-and-brand.md) |
 | 5 | Bindings: the site reads BetterCMS data and each intended leaf or attribute is bound; build, preview and runtime agree | [bindings.md](bindings.md), [frameworks.md](frameworks.md) |

package/dist/skills/bettercms/references/forms-and-interactions.md

@@ -184,6 +184,13 @@ only reveals the next group, to `step` fields; keep one `required` per real ques
 
 `update_form` with `fields` replaces the whole array: send every field you want to keep.
 
+Setup imports two kinds of form already ignored, each kept as a restorable row: the site's own
+sign-in, register and password forms, and a shop's add-to-basket, buy-now or checkout form (it
+posts to the cart and asks only a quantity or a variant). Both stay the site's code. An imported
+form is named for what it is for: its `aria-label`, its one legend, a heading inside it or in its
+own band, else its purpose ("Newsletter signup", "Contact"). Rename it with `update_form` if the
+site calls it something else.
+
 ### 4. Wiring a self-hosted site
 
 - **Next**: `getForm('Name')` (or an id) reads the form from `bcms-content.json`; render

package/dist/skills/bettercms/references/getting-started.md

@@ -85,6 +85,8 @@ and `get_componentize_plan` proposes nothing more.
    with `componentize_sections`, then the repository half (`componentize_sections { codemod: true }`
    when there is no checkout) and `submit_componentize_receipt` ([componentize.md](componentize.md)).
 5. Work the rest through [finish-site.md](finish-site.md) (gap ledger, repair order, proof loop).
+   The gate's `sections` and `style` rows are part of it: a setup whose pages cannot take a new
+   section, a new order or spacing is not finished.
 
 ### Phase 4 — Publish and verify