@bettercms-ai/mcp 0.71.0 → 0.72.1

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,35 @@ 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.
+
+**An imported form's words are edited in the form, and written into the built page.** On a new
+import, setup binds each part of the built `<form>` to its form row: field labels, placeholders,
+help lines, select and radio options, and the submit button's text. Change one with `update_form`
+(`fields[].label`, `placeholder`, `helpText`, `options`, or `submitLabel`) and the next content
+apply writes it into every built page that draws the form, with no rebuild. The built form
+carries the stamps:
+
+| Stamp | On | Says |
+|---|---|---|
+| `data-bcms-form-bound="<formId>"` | the `<form>` | Its parts are this form's. Never `data-bcms-form`: that one means the form posts to BetterCMS. |
+| `data-bcms-form-part` | a part | `label`, `help`, `option` or `submit`, as `BcmsForm` names them. |
+| `data-bcms-form-field="<key>"` | a part or a control | The field it belongs to. |
+| `data-bcms-form-value="form:<formId>:<path>"` | a part shown as text | The address written: `fields.<key>.label`, `fields.<key>.helpText`, `fields.<key>.options.<i>`, `submitLabel`. A placeholder is a `data-bcms-props` entry (`form:<formId>:fields.<key>.placeholder`). |
+
+Only words are written. The lane adds and removes no element and never touches `name`, `id`,
+`for`, `action`, `value`, a validation attribute or a hidden input, so the site's own script and
+endpoint keep working. An option added to the row has no element until the site's code is
+rebuilt, and is reported as not on the page. A fieldset's `<legend>` and an
+`<input type="submit">` stay the code's. A form setup ignored (sign-in, basket) and a form
+already wired with `data-bcms-form` take no stamp. The submit button belongs to the form: its
+text is `submitLabel`, never a page field.
+
 ### 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
 

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

@@ -126,13 +126,30 @@ value to its asset. Check it, never redo it: the binding report's `elementCovera
 | `IMG_DATA_URI`, `IMG_NO_SOURCE` | An `<img>` inlined as `data:`, or filled in by a script | Ship it as a file with a real `src` |
 | `BG_PSEUDO_ELEMENT` | A background on `::before` / `::after` | Move it onto the element, or render an `<img>` |
 | `BG_ON_TEXT` | A background on an element that is itself a text field | Wrap the text, so the box and the words are two elements |
-| `SVG_TOO_LARGE` | An inline `<svg>` illustration past the icon size | Ship it as an `.svg` file in an `<img>` |
-| `SVG_SPRITE`, `SVG_NOT_ICON`, `SVG_DECORATIVE` | A `<use>` sprite, a chart, a nameless glyph | Decoration: leave it, or give a logo `role="img"` and an `aria-label` |
+| `SVG_TOO_LARGE` | An inline `<svg>` past 64 KB | Ship it as an `.svg` file in an `<img>` |
+| `SVG_SPRITE` | A `<use>` naming a symbol the page does not hold, or a sprite FILE the build does not ship (another host's, a relative path) | Inline the symbol in the page, serve the sprite from the site root, or ship the icon as its own `<svg>` |
+| `IMAGE_NOT_ASSET` | A header or footer picture the Media library holds no asset for | Nothing lost: the rest of the region is the Layout's and this picture stays a field of each page. Setup tries it again on the next build |
+| `SVG_NOT_ICON`, `SVG_DECORATIVE` | An `<svg>` holding a script, an HTML island or a remote image; an `aria-hidden` glyph in the nav or footer, or a nameless one on an older import | Decoration: leave it, or give a logo `role="img"` and an `aria-label` |
 | `BG_SPRITE`, `BG_TINY`, `BG_PATTERN`, `BG_DATA_URI`, `BG_STATE` | A sprite, an icon-sized box, a tile, an inlined texture, a hover image | Decoration: leave it |
 
-The first four rows count against the image coverage; the last two do not. A gap you cannot
+The first four rows count against the image coverage; the rest do not. A gap you cannot
 close is reported with its code, never described as done.
 
+An icon a sprite file draws (`<use href="/sprite.svg#shield">`, a same-site `.svg` the build
+ships) is an image field like any inline icon. An icon a FONT draws (`<i class="ph ph-tag">`) is
+a text field holding the class, written to the `class` attribute alone: change the class to
+change the glyph.
+
+`elementGaps` is the same record for everything that is not a picture (`rows` carry a `sample`
+where an image row has a `src`). `EMBED_NOT_VIDEO` (an `<iframe>` that is no video provider's),
+`AUDIO_SOURCE` and `ICON_FONT` (a font icon inside a paragraph that is one rich-text value) are
+shown and editable nowhere, and count against coverage. The rest are declined on purpose and
+never count: `SKIP_LINK`, `FRAMEWORK_UI` (a docs framework's pager, table of contents or
+search), `FRAGMENT_LINK` (an in-page `#` destination under those rules), `ORDINAL_MARKER` (a
+step number the template counts out, on a project imported before step numbers were fields),
+`TEMPLATE_TEXT`, `NOSCRIPT_TEXT` and `HEAD_META_UNMAPPED` (a `<meta>` no native SEO field holds,
+by name).
+
 ## Media host
 
 Use `mediaBaseUrl` from `get_project`: media is served from the CDN origin or the API origin of

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

@@ -42,6 +42,8 @@ webhook. Use the project's webhook secret from the dashboard (the package docs n
 | `readComponents()` | Component definitions from `bcms-content.json` |
 | `BcmsField` | `path`, `kind` (`richtext`/`image`), `as`; server-safe; no wrapper around a single DOM element ([animation.md](animation.md) §10) |
 | `BcmsButton` | A `button` field: `path`, `value`, `className`; one `<a>` with `data-variant` / `data-size`. Style only the looks the site has ([components.md](components.md) §5); server-safe |
+| `BcmsSections`, `BcmsSection` (from `@bettercms-ai/next/sections`) | The page's own sections, drawn in the CMS page's order (below); a server component |
+| `sectionsFor(slug)`, `sectionsStaticProps(slug, own?)`, `sectionsServerSideProps(slug, own)` | The block list, components and forms `BcmsSections` takes, from the snapshot |
 | `sectionRootAttrs(block)` | Spread on a section root your own code renders: `data-bcms-block`, `data-bcms-style` and the block's style, plus `data-bcms-hide` when `style.hideOn` is set: ship `RESPONSIVE_CSS` (exported here) in your global CSS ([components.md](components.md) §5) |
 | `bind`, `bindProps` | Binding attributes; instance-aware inside components |
 | `BcmsForm` + `getForm(idOrName)` | Forms from the snapshot ([forms-and-interactions.md](forms-and-interactions.md)) |
@@ -60,6 +62,91 @@ Rules:
 - The package ships no sitemap or robots helper. Write `app/sitemap.ts` and `app/robots.ts`
   yourself from published content, and leave out pages marked noindex.
 
+## Sections in the CMS order
+
+A page whose sections are written in its own 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).
+
+App Router, in a server component:
+
+```tsx
+import { sectionsFor } from "@bettercms-ai/next";
+import { BcmsSections, BcmsSection } from "@bettercms-ai/next/sections";
+
+export default function Home() {
+  return (
+    <main>
+      <BcmsSections {...sectionsFor("home")}>
+        <BcmsSection bind="hero">{(root) => <Hero rootProps={root} />}</BcmsSection>
+        <BcmsSection bind="code:sec1"><LogoCloud /></BcmsSection>
+        <BcmsSection bind="features"><section className="features">…</section></BcmsSection>
+      </BcmsSections>
+    </main>
+  );
+}
+```
+
+Pages Router: the page also renders in the browser, so the list is a page prop.
+
+```tsx
+import { sectionsStaticProps, type SectionsData } from "@bettercms-ai/next";
+import { BcmsSections, BcmsSection } from "@bettercms-ai/next/sections";
+
+export default function Home({ bcmsSections }: { bcmsSections: SectionsData }) {
+  return <BcmsSections {...bcmsSections}>…</BcmsSections>;
+}
+export const getStaticProps = sectionsStaticProps("home");
+```
+
+A page with its own data function passes it in, and the list joins the props it answers:
+`export const getStaticProps = sectionsStaticProps("home", pageStaticProps)`, or
+`sectionsServerSideProps` for `getServerSideProps`. `--sections` writes this for you.
+
+A page that only returns a view (`return <HomeView locale="en" />`) has its sections in the
+view's file, and `--sections` wraps them there: it follows the import (relative, a `paths` alias
+of the repository's tsconfig or jsconfig, an index file or a barrel's re-export) up to three
+components down. One view often serves several pages (`/` and `/fr`), so the page reads its own
+list and hands it over, and the view takes it as an optional prop:
+
+```tsx
+// app/fr/page.tsx
+export default function Page() {
+  return <HomeView locale="fr" bcmsSections={sectionsFor("fr")} />;
+}
+
+// views/home-view.tsx: a server or a "use client" component, it only names the type
+export default function HomeView({ bcmsSections, locale }: Props & { bcmsSections?: SectionsData }) {
+  return (
+    <main>
+      <BcmsSections {...(bcmsSections ?? { page: "" })}>
+        <BcmsSection bind="hero"><Hero locale={locale} /></BcmsSection>
+        …
+      </BcmsSections>
+    </main>
+  );
+}
+```
+
+A render that was handed no list (a route the CMS has no page for) keeps the source order. In the
+Pages Router the page passes on the prop it got: `<HomeView bcmsSections={bcmsSections} />`.
+
+- A bind is the family of the section's first bound field (`features-title` → `features`): the
+  `bind` on the page's `component` block. A block bound to a section renders it at the block's
+  position; a section added in the editor (no bind) renders through `BcmsBlocks`.
+- The stamp goes on the section's own root. One DOM element (`<section>`) gets
+  `data-bcms-block`, `data-bcms-style` and the block's style cloned onto it. A COMPONENT child
+  cannot be handed unknown props, so write it as a function and spread `root` on the element the
+  component renders (`<section {...rootProps}>`). Without the function it is stamped on a box:
+  `display:contents` while its block has no style, one `display:flow-root` box carrying the
+  style once it has ([animation.md](animation.md) §10).
+- A section 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 sections; from then on it is a removed one.
+  Write a bind bare only when the page already places it (`get_page`), otherwise `code:`.
+- `blocks` null (no snapshot) renders every child in source order, untouched.
+- Never inside a `"use client"` file: it reads its children's own elements, which a client
+  component cannot do across the server boundary.
+
 ## Lists, pagination and missing content
 
 - `listEntries(model, { page, perPage })`: `page` is 1-based; `perPage` defaults to 20 and the

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

@@ -35,7 +35,8 @@ that reads them.
 - Publishing copies the stored draft to live, so what you checked in the draft is what ships.
 - **Many at once**: `publish_entries` { action: 'publish' | 'unpublish', entryIds, pageIds } takes
   up to 100 of each in one call (pages publish only). Each item still passes its own gates, and
-  nothing stops the run: read `failed` for every refusal and its reason.
+  nothing stops the run: read `failed` for every refusal and its reason, then `outcome` for what
+  the served pages show (the same shape `update_page` returns on a publish, below).
 - **Throw away a draft**: `discard_draft` with `entryId` or `pageId` returns it to exactly what is
   live; a page also drops its unpublished Layout overrides (`no_published_version` if it never
   went live: delete it instead).
@@ -64,6 +65,19 @@ renders rows no address names, or was built empty). That publish waits for its b
 the list shows N rows") and fails with the reason if the build still shows the page's own rows: the
 site's code renders the list itself. `get_next_steps` names what is waiting.
 
+A static page whose own code fixes its sections takes all of it in place too, when the project's
+in-place structure switch is on: the publish writes the page's block list into the built HTML.
+The code's bands stand in the published order, a removed one is cut, a section added in
+BetterCMS is drawn between them, and every root takes its block's style. No repository change
+and no build; each rebuild is put right the same way. The gate's `sections` row says which
+routes take it (`accepts: "in-place"`).
+
+A collection's item pages take it per TEMPLATE: the collection page's sections are the
+template's, held once, so a section added to that page (`update_page` on the collection page)
+stands on every entry's route, and an entry has no sections of its own. Its publish reads one
+row for all of them (`route` `blog/*`). The entry's body is a section too: add sections around
+it or move it, and space it through its field's style, since its element is the field's.
+
 The SEO a page or entry stores is what its `<head>` says, whenever it was set: the title, the
 description, the canonical, the card fields, a `noindex` that is on. A field left empty keeps what
 the build rendered, and a site default only fills a tag the build has none of. Only a real choice
@@ -79,14 +93,52 @@ Builds run `build:bcms` instead of `build` when `package.json` declares it. Keep
 of it and every step the build needs in: `"build": "astro check && astro build"` beside
 `"build:bcms": "astro build"`. The convert codemod adds one to a repo whose build chains a check.
 
+### Add a section, or set its spacing
+
+One call each, on any page (a page BetterCMS draws, a code-built one, a collection template):
+
+- **Add a section here**: `update_page { pageId, blockJson: { insertSection: { componentId, after: "<block id>" } } }`.
+  `componentId` is a component from `list_components`; a `builtin:*` id is copied into the project
+  once and the copy is placed. Place it with `at` (an index into the page's sections), `before`
+  or `after` (a section's block id from `get_page`); none of the three adds it last. `style` and
+  `overrides` set its block style and its copy in the same call.
+- **Set spacing on this section**: `update_page { pageId, blockJson: { sectionStyle: { blockId, style } } }`.
+  Each key of `style` replaces the stored one and `null` unsets it: `paddingTop`, `paddingBottom`,
+  `paddingSides` (px, 0 to 240), `spaceTop`, `spaceBottom`, `spaceSides` (the spacing tokens),
+  `bg`, `bgCustom`, `contentWidth`, `contentAlign`, `theme`, `corner`, `shadow`, `border`,
+  `opacity`, `hideOn`. A key the block style does not have is refused (`INVALID_STYLE`).
+
+The server edits the page as stored, so nothing else on it is resent or overwritten; send
+`ifMatch` to refuse a page that changed since you read it. Both save a DRAFT: add
+`status: "published"` to the same call, or publish after. Then read the answer, top down:
+
+1. `held`: the draft is saved and the live page will NOT show it. It names the reason and the one
+   action (below). Do the action; do not report the change as made.
+2. `outcome` (on a publish): `status` `live` is every value found on the served page. `partial`
+   lists what is not in `notLive`, each with its `reason` and `action` (the table under Reading
+   `get_deploy_status`). `next: "get_deploy_status"` means it is not judged whole: nothing has
+   looked at it yet, or a section change is still being written (`NOT_CHECKED`). It resolves by
+   itself to live or held: poll `publishes` there before you say anything is live.
+3. `section`: the block's `id` and `index`, to place the next one beside it.
+4. `warnings`: `COMPONENT_DRAFT` is a section that renders nothing until `publish_component`.
+
+Refusals: `SECTION_NOT_FOUND` (the answer lists the page's section ids), `POSITION_OUT_OF_RANGE`,
+`COMPONENT_NOT_FOUND`, `BUILTIN_NOT_FOUND`. A whole `blockJson` array still replaces the page's
+sections; use it to move or remove one, with `ifMatch`.
+
 ### A section change that is held at the write
 
-`update_page` and `compose_pages` save the draft and answer with `holds` when a `blockJson` adds,
-moves or removes a section the live page cannot show yet. Each hold has a `reason`, a `message`,
-the `sections` it is about and the one `action`. Never report such a write as done:
+`update_page` and `compose_pages` save the draft and answer `held` first (with `holds`) when a
+write adds, moves or removes a section the live page cannot show yet. Each hold has a `reason`,
+a `message`, the `sections` it is about and the one `action`. Never report such a write as done:
 
 - `CODE_FIXED_SECTIONS`: the site's code fixes this page's sections, so no publish ships the
-  change. The action is `componentize_sections` with `codemod: true`; after its build, publish.
+  change. Read the route's `sections` row in `get_next_steps` (`receipt.gate`): its `fixCode`
+  names the lane ([finish-site.md](finish-site.md)). `enable-in-place-structure` is the user's
+  switch and needs no code. `run-sections-conversion` is the wrap: `componentize_sections` with
+  `codemod: true` and the `digest` of `get_componentize_plan`, or, when that answers `skipped`
+  (no repository the platform may commit to), `npx @bettercms-ai/convert@latest --sections --root .`
+  in a checkout ([componentize.md](componentize.md) §5). After its build, publish.
 - `SECTION_NEEDS_BUILD`: the build draws the page's sections from BetterCMS. Publish: the build
   starts by itself, and a move or a removal needs none.
 - `STRUCTURE_UNMEASURED`: nothing has measured the page. Publish, then read the publish's outcome
@@ -117,13 +169,29 @@ the `sections` it is about and the one `action`. Never report such a write as do
 | `VALUE_REFUSED` | held | Bind the field to an element that can hold its value |
 | `APP_DOES_NOT_READ` | held | Convert in code: make the page's code read the published field |
 | `ROWS_NEED_BUILD`, `SECTION_NEEDS_BUILD`, `NEEDS_BUILD` | held | Wait for the build the publish started |
-| `STRUCTURE_UNBOUND` | refused | Let BetterCMS control section order (componentize with the codemod) |
+| `STRUCTURE_UNBOUND` | refused | The fix the route's `sections` gate row names: the in-place switch, or the sections conversion |
 | `SECTION_MISSING` | held | The same: the served page does not render the section |
-| `STYLE_NOT_PAINTABLE` | held | Run editor setup so section roots carry `sectionRootAttrs` |
+| `SECTION_NOT_ON_PAGE` | held | In place: a section of the site's own code has no band on this page. The sections conversion, or remove the placement |
+| `SECTION_NOT_RENDERABLE` | held | In place: the added section's component is not published, or it needs a form. `publish_component`, then publish the page again |
+| `STYLE_NOT_PAINTABLE` | held | Rebuild once the section root carries the style marker (`sectionRootAttrs`, or the codemod's `--upgrade-sections`: [components.md](components.md)) |
 | `WINDOW_NOT_OPEN` | held | Nothing: it goes live when its window opens |
 | `ROUTE_NOT_OWNED` | held | Change one of the two page paths that share the URL |
 | `APP_UNREACHABLE`, `NOT_CHECKED`, `EDGE_PENDING`, `IMAGE_UNAVAILABLE`, `STRUCTURE_UNMEASURED` | unverified | Poll again; publish again if it stays |
 
+Each row's `action.code` is one of these, and `get_next_steps` lists every held or refused value
+as `publish-held` until it is gone:
+
+| `action.code` | What you do |
+|---|---|
+| `rebuild` | No tool rebuilds: change the site's code if the reason names it, then ask the user to Rebuild from Publishing (or `deploy_project` from a checkout) |
+| `wait_for_build` | Poll `get_deploy_status` until the build the publish started is live |
+| `convert_in_code` | Make the page's code read the field ([bindings.md](bindings.md)), then release |
+| `control_section_order` | The route's `sections` gate row names it: the in-place switch (the user's), or `componentize_sections` with `codemod: true` (else `convert --sections` in a checkout), then release |
+| `editor_setup` | `editor_setup` |
+| `rebind` | Bind the field to an element that can hold it, in the site's code |
+| `resolve_route` | Change one of the two page paths |
+| `wait`, `retry` | Poll again; publish again if it stays |
+
 ### Deploy to Vercel or Netlify
 
 To serve a `managed` or `hybrid` site from the owner's own Vercel or Netlify account, call

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

@@ -53,7 +53,8 @@ values as they are; rewriting copy is a separate, reported recommendation.
 | `<meta name="description">` | `metaDescription` | Copy verbatim. Aim for 120–160 characters; the audit flags only a missing one and one over 160. When the source has none, take a `generate_seo_meta` suggestion and list it for review |
 | `og:title`, `og:description`, `og:image`, `og:type` | `og.title`, `og.description`, `og.image`, `og.type` | Write a key only when it differs from the meta title, the description or the site default. Upload the image first and store its media URL |
 | `twitter:card`, `twitter:title`, `twitter:description`, `twitter:image` | `twitter.card`, `twitter.title`, `twitter.description`, `twitter.image` | Same rule as OG |
-| `twitter:site` | `update_seo` `seoDefaults.twitterHandle` | Once per site |
+| `twitter:site` | `update_seo` `seoDefaults.twitterHandle` | Once per site. A BetterCMS-built import fills it, the card and `og:type` from the home page's head where the project holds none |
+| `keywords`, `author`, `theme-color`, a site verification tag | nothing | No native key stores them. The binding report's `elementGaps` lists each by name (`HEAD_META_UNMAPPED`); report them |
 | A site-wide share image | `update_seo` `seoDefaults.ogImage` | Then pages inherit it and `og.image` stays empty |
 | Canonical pointing at the page itself | nothing | A hosted page gets its own canonical |
 | Canonical pointing at another URL | `canonical` | Keep it: someone consolidated those URLs on purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/mcp",
-  "version": "0.71.0",
+  "version": "0.72.1",
   "type": "module",
   "description": "BetterCMS MCP server — schema, content, forms + components authoring tools over the Management API, authed via OAuth device-code.",
   "bin": {