@bettercms-ai/mcp 0.71.0 → 0.72.1

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,75 @@ 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.
+
+**A page that only draws a view.** Where the page file is a shell (`<HomeView locale="en" />`,
+alone or inside its layout) the sections are written in the view, and `--sections` wraps them
+there: it follows the import (relative, or a `paths` alias the repository's own tsconfig or
+jsconfig declares, index files included) up to three components down, to the first file that
+writes two or more sections or writes its run inside a layout. One view often serves several
+pages (`/` and `/fr`), so the view cannot name the page. Each page hands it down, and the view
+reads it:
+
+```astro
+<!-- src/pages/fr/index.astro -->
+<HomeView locale="fr" bcmsPage="fr" />
+
+<!-- src/views/HomeView.astro: `bcmsPage?: string` joins its Props -->
+<MainLayout>
+  <BcmsSections page={Astro.props.bcmsPage ?? ""}>
+    <Fragment slot="hero"><HeroSection title={copy.hero.title} /></Fragment>
+    …
+  </BcmsSections>
+</MainLayout>
+```
+
+Each page then follows its own CMS page's list through the one set of slots. A route that hands
+the view no page (the CMS has none for it yet) renders the source order. A slot is bare only
+when every page drawing the view places that bind. A dynamic route's view (`blog/[id].astro` →
+`BlogPostView`) is wrapped the same way with `template`. Write it by hand in this shape when the
+codemod refuses the view ([componentize.md](componentize.md) §5).
+- 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 +142,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,61 @@ 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 file that only draws a view component (`<HomeView locale="en" />`) is wrapped in the
+view's file, where its sections are written; the dry run names that file per page, and the page
+itself only gains the prop that tells the view which page it is ([astro.md](astro.md),
+[next.md](next.md)). A lone component that is itself one section is wrapped in the page.
+
+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 |
+| `VIEW_IMPORT_UNRESOLVED` | Draws one component, and its import names no file: an alias no tsconfig or jsconfig of the repository declares (one inherited through `extends` is not read) | Declare the alias in the config's own `compilerOptions.paths`, or import the view by a relative path; run again |
+| `VIEW_DEPTH_EXCEEDED` | Its sections are more than three components below the page | Wrap by hand in the file that writes them, and pass the page down ([astro.md](astro.md), [next.md](next.md)) |
+| `VIEW_SHARED_INCOMPATIBLE` | Draws a view another page draws too, and the CMS names the view's sections differently on the two (or one is a page and the other a collection's item template, in Astro) | Give each page a view of its own, or make the two CMS pages place the same binds, then 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

@@ -32,6 +32,13 @@ defaultValue? }`.
 - **A `button` prop is one unit.** Its value is `{ label, href, variant?, size?, arrow?, icon?,
   newTab? }` and its `target.path` is `props` on a `button` block. For a new component never
   declare a label prop plus a url prop: the two drift apart on the first edit.
+- **A button the site's own script handles has no href.** Its value is `{ label, action: "code",
+  variant?, size?, arrow?, icon? }`: a `<button type="button">` that opens a dialog, accepts
+  cookies or starts a tour. The label and the look are edited; the click stays the site's.
+  `href`, `newTab` and `rel` beside `action: "code"` are refused, and a value with neither an
+  href nor the action is refused as before. Setup derives these as button fields on a new
+  import. A control of the page itself is never one: a menu or theme toggle, a carousel arrow, a
+  dialog's close, an accordion or tab trigger, a copy button, a pagination step.
 - `target.blockId` + `target.path` must point at a real block and property inside the
   component's own `blockJson`. Why: rendering copies each prop's value to that target; a target
   that does not exist renders the default and the edit goes nowhere.
@@ -192,16 +199,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
@@ -219,15 +234,43 @@ A code-built site ships only what its templates draw, whatever the page's `block
   `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 every look control (style, size, arrow, icon, new
-  tab) applies on the canvas and on publish.
+  tab) applies on the canvas and on publish. A value with `action: "code"` renders
+  `<button type="button" data-bcms-button>` with the same children and no href: attach your
+  handler to it as before. A publish writes its label and look and never an href, a target or a
+  rel, and never turns it into an anchor.
 - **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. |
+
+  What counts as a button is one rule for the family and for the fields: what the site names one
+  (`btn`, `button`, `cta`, `role="button"`), or what its stylesheet paints as one (a fill or a
+  border of its own). Two looks paint nothing at rest and still count: a ghost, by its own padded
+  box, and a text link drawn as a row that underlines. In a menu those two count only beside a
+  painted button.
+
+  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.