@bettercms-ai/mcp 0.70.0 → 0.71.0

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

@@ -79,6 +79,19 @@ 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.
 
+### 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:
+
+- `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.
+- `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 +105,24 @@ 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 | Let BetterCMS control section order (componentize with the codemod) |
+| `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` |
+| `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 |
 
 ### Deploy to Vercel or Netlify
 

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.71.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"
   },