@bettercms-ai/mcp 0.70.0 → 0.72.0

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,6 +93,57 @@ 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 `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. 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
+  in `get_deploy_status`.
+
 ### Reading `get_deploy_status`
 
 - `release` is the newest release: `id`, `sha`, `status`, `phaseMarks`, `error`, `createdAt`.
@@ -92,6 +157,40 @@ of it and every step the build needs in: `"build": "astro check && astro build"`
   and ready on staging while production keeps the older sha, until `promote_project` runs.
 - The poll is finished only when `slot` is `current`, or when `awaitingPromote` is false and
   `productionSha` equals the sha you deployed.
+- `publishes` is the newest publishes, value by value. `status` `live` means every published value
+  was found in the file the site serves that page from. `partial` means some were not: `summary`
+  counts them ("3 of 4 live · 1 held") and `notLive` lists each with its `route`, `address`,
+  `state`, `reason` and the one `action` that fixes it. Never tell the user a publish is live
+  while it reads `partial`: relay the reason and do the action, then poll again.
+
+| `reason` | `state` | The one action |
+|---|---|---|
+| `NOT_STAMPED` | held | Rebuild: the built page has no element for the field and does not show it |
+| `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 | 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 |
+| `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
 

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/dist/skills/bettercms/references/worked-examples.md

@@ -109,8 +109,8 @@ Value (`set_page_content`):
     "hero_eyebrow": "Freight visibility for mid-size shippers",
     "hero_title": "Know where every container is before your customer asks.",
     "hero_lede": "Live ETAs from 140 carriers, delays flagged before they cost you, and one shared view for ops and sales.",
-    "hero_primary": { "label": "Book a demo", "href": "/demo", "variant": "primary", "arrow": true },
-    "hero_secondary": { "label": "Start free trial", "href": "https://app.kestrelfreight.com/signup", "variant": "secondary" },
+    "hero_primary": { "label": "Book a demo", "href": "/demo", "arrow": true },
+    "hero_secondary": { "label": "Start free trial", "href": "https://app.kestrelfreight.com/signup" },
     "hero_image": {
       "url": "/img/hero-harbor-2560.jpg",
       "altText": "Container cranes over a quiet harbor at dusk",
@@ -149,6 +149,8 @@ Bound template (classes unchanged, shortened here):
 - The image binding sits on the `<img>`, not the `<picture>`. The alt text travels in the image
   value (`altText`): a publish writes it to the bound element's `alt`. When `get_conversion_brief`
   lists a separate alt path, declare that path in `data-bcms-props` with kind `text`.
+- Neither button value names a `variant`: the anchors keep the site's own `btn-primary` and
+  `btn-ghost`, and the release reads those two looks into the project's Button family.
 - An `href` is kind `url`, never `text`. The label gets its own `<span>` so a save does not erase
   the arrow; the arrow is drawn by `BcmsButton` ([components.md](components.md)), so remove the
   hand-written `<svg>` once the button renders through it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/mcp",
-  "version": "0.70.0",
+  "version": "0.72.0",
   "type": "module",
   "description": "BetterCMS MCP server — schema, content, forms + components authoring tools over the Management API, authed via OAuth device-code.",
   "bin": {
@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "@bettercms-ai/device-auth": "^0.2.0",
-    "@bettercms-ai/sdk": "^1.28.0",
+    "@bettercms-ai/sdk": "^1.29.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.3.6"
   },