@bettercms-ai/mcp 0.69.0 → 0.70.0

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

@@ -55,7 +55,11 @@ build. Pass `apiUrl` and `workspace` as options, or let the snapshot supply them
 
 A section root your own code renders spreads `sectionRootAttrs(block)` from `@bettercms-ai/astro`
 (`data-bcms-block`, `data-bcms-style` and the block's style), so the editor can move it and offer
-its spacing handles ([components.md](components.md) §5).
+its spacing handles ([components.md](components.md) §5). It adds `data-bcms-hide` when `style.hideOn` is set: put `RESPONSIVE_CSS` (exported here) in your global CSS.
+
+`<BcmsBlocks>` does not render a block outside its `window`, read against the `now` prop (default:
+render time). Pass `showScheduled` on a draft preview to draw it, marked `data-bcms-window`
+([publishing.md](publishing.md) §6).
 
 `bind` and `bindProps` from `@bettercms-ai/astro/bindings` produce the same attributes as the Next
 helpers. Use them inside component instances so addresses resolve to the instance

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

@@ -207,3 +207,50 @@ still renders hard-coded copy is not connected. Client components never receive
 - `get_binding_report`'s `help.percent` is 100: every bound field also tells its editor what it
   is for. Binding a leaf makes it editable; help text makes it usable
   ([content-modeling.md](content-modeling.md), "Writing help text").
+
+## Reading the binding report and the conversion receipt
+
+`get_binding_report` per slot (`slot` is `current` or `staging`; on a promote-gated project read
+`current`, the tree the editor frames). Every figure, `unaddressable` included, is measured per
+slot. `sha` is the build the report describes; `refreshRequired` is true when that is not the
+build the slot serves. `builtRoutes` lists the routes the live build has HTML for (null = cannot
+say). `layoutIncomplete` lists Layout paths the last content apply could not write (their publish
+waits); `layoutUnread` lists Layout fields no route reads (`layoutUnreadJudged` false = not
+judged).
+
+- **Before any release** there is no report: pages 0, mode null, `refreshRequired` true.
+  `refreshReason` `never-generated` means only a release BetterCMS builds and serves writes a
+  report, so a headless site never gets one, redeploy or not; `outdated` means the next release
+  rewrites it.
+- **`unmatched` reasons**: `not-declared`, `ambiguous-text`, `no-element`, `declared-only`,
+  `needs-wrap`, `refused`, `layout-owned`, `page-owned`, `layout-locator-stale`,
+  `locale-unvarianted`, `svg-unavailable`, `partial`, `unstamped` (a page list the content apply
+  left as built; `kind` reads `list <bound>/<total>`), `mismatch` (a text-match stamp whose element
+  shows more than the value, or no longer the text it was matched on, `data-bcms-from`; never
+  written) and `report-outdated`.
+- A clean report proves each non-empty field has an element carrying its path, nothing more. A Global
+  Section counts only on the routes that render it (`layoutRoutes`).
+- **`unaddressable`** is the copy the report cannot see: visible live text no field owns, by
+  route and bucket, biggest first (null = unmeasured: diff the visible text against the entry
+  values). Over `count / visible > 0.02`, fix it in the source (wrap the run in an element the
+  codemod can bind, or declare `<BcmsField path=…>`), deploy and read again (playbook §11).
+- `canvas.lane` is the editor's live-preview lane (`bridge`, `draft-route`; `none` sends you to
+  `get_next_steps`). `coverage.error` `nothing-bound` means no element of this build is bound, so
+  its percentage describes another site.
+
+`submit_conversion_receipt` answers `complete` (`sourceComplete` is the receipt's own verdict;
+`liveChecks` gives the last release's `structureUnstamped` route count and `reportSha`) and
+`pendingTotal`, and echoes the first 40 pending rows with their `fix`:
+`{ action, file, line, col?, snippet, why?, kind? }`. `action` is one of `wrap-span`,
+`declare-attr`, `bind-expression`, `declare-richtext`, `bind-data`, `manual`; `snippet` and `why`
+say what to change. On a `declare-richtext` with `kind: document`, bind the one element wrapping
+every block of the Body, never the paragraph holding its first. A 404 `unknown-brief` means that
+digest was never issued here. The same run owes the `--forms` receipt, submitted as a second call
+under the same `briefDigest`, and the `styleEdits` of `convert --verify-styles` inside this
+receipt; one listing a changed class, className or style is refused with 409 `style-edits`.
+
+The complete brief (`get_conversion_brief { complete: true }`) also carries `forms` (id, status,
+fields, submitUrl). After the binding pass, run the codemod's forms mode (`npx
+@bettercms-ai/convert --forms`, with the brief and a receipt file) to wire them into the
+repository's own `<form>` elements. Read `forms.pending`, and publish every form `forms.notes` names in the Forms tab: a draft
+form rejects every submission with a 403.

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

@@ -25,8 +25,9 @@ Inside a section, pick the smallest shape that holds the children:
 
 - **Small identical items** (FAQ rows, feature bullets, logos): a `group` or `table` prop.
 - **One replaceable child with its own layout or variants** (a hero's media treatment): a `slot`
-  prop. It holds exactly one instance, and never sits inside a `group` or `table` row.
-- **Several different children**: the section's ordered children, not a list of slots.
+  prop. It holds one instance, and never sits inside a `group` or `table` row.
+- **Several different children**: the section's ordered children when the set is fixed; a `slot`
+  prop with `config.multiple` when the editor picks and orders them.
 
 Never let a component contain itself, directly or through a child.
 
@@ -40,8 +41,9 @@ Never let a component contain itself, directly or through a child.
    prose body and lists of object rows are sections. Read `pending` for what it will not offer:
    `NO_GROUP_ROOT` (keys are still the derive lane's own, such as `h1-welcome`: rename them into
    families first), `NOT_A_SECTION` (a lone scalar or page metadata; `detail: ENTRY_METADATA` is
-   a template's frontmatter, `detail: DECLINED` a group the user declined) and `IMAGE_AS_TEXT`
-   (a text field holding an image path; it plans once the field is an image). A nav, footer or
+   a template's frontmatter: author, images, tags and dates stay entry fields; `detail: DECLINED`
+   is a group the user declined) and `IMAGE_AS_TEXT` (a text field holding an image path; it plans
+   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.

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

@@ -41,11 +41,31 @@ defaultValue? }`.
 - A prop takes `showIf` (`{ match, rules: [{ field, op, value? }] }`): hidden until SIBLING props match. `op` is `eq`, `neq`, `in` or `isSet` (no `value`); model fields take the same four.
 - `update_component` replaces the whole `props` array. Read with `get_component`, change, write
   all props back.
-- `select` and `multiselect` need `config.options`; `slot` holds one nested component instance;
-  `form` holds one Form document.
+- `select` and `multiselect` need `config.options`; `slot` holds one nested component instance,
+  or a list of them with `config.multiple`; `form` holds one Form document.
 - `slot` and `form` are reference-shaped: `target.path` is `props` (the whole envelope) on an
   empty `component` or `form` block, and their values are `{ componentId, overrides? }` and
   `{ formId }`. Neither may appear inside a `group` or `table` row.
+- **A `slot` with `config.multiple: true` holds a list.** Its value is
+  `[{ componentId, overrides? }, ...]` and its `target.path` is a container's child list:
+  `props.children` on a `section` block, or `props.columns.<n>` on a `columns` block (never
+  `props` on a `component` block). Each item is drawn there as a child component, in order.
+  Until a placement sets the slot, the children the definition holds in that list are shown;
+  `[]` shows none.
+  - `config.maxItems` defaults to 12 and cannot pass 50. `config.minItems` and
+    `config.componentIds` (which components may be listed) are checked on every write.
+  - An item may also carry `style` (use it for `hideOn`) and `window` with `from` / `until`
+    as UTC to the second (`2026-11-27T00:00:00Z`). A `defaultValue` must be an array and takes
+    no `window`.
+  - A write is a 400 whose message starts with the code: `slot_too_many`, `slot_too_few`,
+    `slot_item_invalid`, `slot_component_not_allowed`, `slot_component_unknown` (not a
+    component of this project), `component_cycle` (a component would end up inside itself,
+    through any chain), `component_too_deep` (more than 10 levels), `slot_target_invalid`,
+    `slot_not_multiple` (a list sent to a single slot). A value that is already stored is not
+    refused when the page is saved again.
+  - A child's copy is not click-to-edit on the canvas. Change it in the placement's
+    `overrides.<slot key>` list with `update_page`.
+  - Publish every listed component: a draft child renders nothing, like any draft component.
 - **A `form` prop stores an id, nothing more.** Modelling the questions again as props gives you
   two answers to "what does this form ask?", and they diverge at the first edit on either side.
   The save schema is `.strict()`, so posting the hydrated form object back is a 400, not a silent
@@ -81,6 +101,12 @@ source? } }`.
   component with a `sectionType`. A true one-off is a `section` block whose `props.children` hold
   its blocks.
 - Components that share a `sectionType` are one family: its variants.
+- **A built-in section is a starting point, not a thing you place.** `list_components` shows the
+  locked `builtin:*` blueprints; `create_component` with `from: "builtin:hero-centered"` copies
+  one into the project as an ordinary draft component, then edit and publish it like any other.
+  Whatever you send (`name`, `slug`, `props`, `blockJson`, `sectionType`, `category`) wins over
+  the copy. `list_components` `sourceKey` says which built-in a component came from. A copy
+  never follows later changes to the built-in. An unknown id is 404 `BUILTIN_NOT_FOUND`.
 - **Give every component a library `category` as well.** Why: `sectionType` groups a family, the
   category is how the component library lists it — an uncategorised component is created fine and
   is then hard to find in the picker, which is where a human looks for it.
@@ -128,7 +154,7 @@ Handle by code, never by retrying the same call:
 |---|---|---|
 | `COMPONENT_BLUEPRINT_MATERIALIZATION_REQUIRED` | You tried to publish a platform built-in | Create a project-local component from it, publish that |
 | `COMPONENT_PROJECT_SCOPED_RELEASE_REQUIRED` | The component is workspace-global | Create a project-local variant, publish that |
-| `COMPONENT_IMPLEMENTATION_NOT_READY` | A REPO-managed component lacks exact evidence and human approval, or a variant-group member's family contract is unpublished. Never a `create_component` component outside a variant group | Report `readiness`; the owner resolves it in the dashboard |
+| `COMPONENT_IMPLEMENTATION_NOT_READY` | A REPO-managed component lacks exact evidence and human approval, or a variant-group member (the provisioned navigation and footer) has a family contract that is unpublished. Never a `create_component` component outside a variant group: that one is dashboard-managed and publishes on the preflight alone | Report `readiness`; the owner resolves it in the dashboard |
 | `COMPONENT_ORCHESTRATION_V2_REQUIRED` | The project runs implementation in Agent Dock | Continue there; stop here |
 | `COMPONENT_PUBLISH_CONFLICT` | The component or its evidence changed mid-publish | Re-read with `get_component`, then publish once more |
 | `COMPONENT_PROJECT_CONTEXT_MISMATCH` | The component's `projectId` differs from the request's project scope | Call with the component's own project |
@@ -311,4 +337,13 @@ stored list.
    siblings.
 2. `get_site_composition`: every page is sections; every component you meant to publish is
    published.
+   - Per page: `kind` is `blocks`, `fields-only` or `empty`. `nonComponentBlocks` are loose
+     top-level bands the editor's section lane cannot outline.
+   - Per placement: the component's `status` is `published`, `draft` or `missing`. `inPicker` is
+     false for a component with no `sectionType`: "Add a section" does not offer it.
+     `emptyRequiredProps` is reported only here.
+   - Site-wide: `components` counts published and draft, `awaitingEvidence` and
+     `awaitingApproval`. A person approves in the dashboard, one component at a time. Then the
+     `notInPicker` and `unused` ids, and `layout.placements`: the chrome placed in the Global
+     Layout draft.
 3. `get_binding_report` on a page that uses the component: instance values bind.

package/dist/skills/bettercms/references/content-modeling.md

@@ -301,7 +301,8 @@ production cannot store it. Translate before the first write.
 | `string` | `text` with `richText: false` | `text` |
 | `text` | `longtext` | `text` |
 | `richtext` | `richtext` for section copy; `document` for the one body | `richtext` |
-| `number`, `rating` | `number` | `number` |
+| `number` | `number` | `number` |
+| `rating` | `number` with `config.min`, `max`, `step` and `ui.control: "rating"` (stars) | `number` |
 | `boolean` | `boolean` | `boolean` |
 | `slug` | `slug` (an entry's own slug stays on the entry) | `text` |
 | `url`, `link` | `link` | `link`; `url` for a media or embed address |
@@ -309,10 +310,10 @@ production cannot store it. Translate before the first write.
 | `date`, `datetime` | `date`, `datetime` | `date` (`YYYY-MM-DD`); a datetime stays `text` |
 | `color` | `color` | `color` |
 | `select` | `select` | `select` with `config.options` |
-| `multiselect`, `tags` | `array` (`itemType: "text"`); a taxonomy is a collection plus `multi-reference` | `multiselect` with `config.options` |
+| `multiselect`, `tags` | `multiselect` with `config.options` (a `string[]`; `config.allowCustom` for free tags, `min`/`max` count the choices); a taxonomy with its own pages is a collection plus `multi-reference` | `multiselect` with `config.options` |
 | `image` | `image` | `image` |
 | `file`, `video` | `file`; a hosted video URL is a `link` | `file`; `url` for a hosted video |
-| `icon` | `text` with `richText: false` | `icon` (an icon name or an image) |
+| `icon` | `icon` (an icon name or an uploaded image) | `icon` (an icon name or an image) |
 | `button` | `button` | `button`: one prop targeting the `props` of a `button` block (§4) |
 | `reference` | `reference`; `multi-reference` for many | none: keep it on the model |
 | `code` | `longtext` | `text` |
@@ -323,12 +324,14 @@ production cannot store it. Translate before the first write.
 | `array` of objects | `repeater` | `table` |
 | `array` of strings | `array` (`itemType: "text"`) | `table` |
 | `array` of several item shapes | `modular` with `config.blockSlugs` (create the block models first) | separate components |
-| `slot` | `sections` or `component-ref` | `slot` (one instance) |
+| `slot` | `sections` or `component-ref` | `slot` (one instance; a list with `config.multiple`) |
 | a form `reference` | a `form` block inside the section | `form` |
 
-V2 features with no production shape are dropped and reported, never faked: typed table columns,
-per-breakpoint values, per-field localization, a slot with several
-children (several sections or nested components instead).
+V2 features with no production shape are dropped and reported, never faked: a per-cell table
+type, per-breakpoint values (only `style.hideOn` differs by breakpoint) and per-field
+localization. Two have a shape now: typed table columns are a `repeater` with one field per column
+and `ui.layout: "table"`, and a slot with several children is a `slot` prop with `config.multiple`
+([components.md](components.md) §1).
 
 | The plan says | Production word |
 |---|---|

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

@@ -136,7 +136,7 @@ match when the sequence is equal and optional parts are missing only at the ends
 |---|---|
 | Two or more siblings of one shape (cards, tiers, logos, questions, steps) | A repeater. Inside a component: a `group` or `table` prop |
 | A list of plain strings (check-mark bullets) | An `array` of scalars. No icon field, no link field |
-| Siblings of different kinds in one grid (a card, a quote, a big number) | The section's ordered children. A `slot` prop holds ONE instance, so it is not a list |
+| Siblings of different kinds in one grid (a card, a quote, a big number) | The section's ordered children. When the editor picks and orders them, a `slot` prop with `config.multiple`; a plain `slot` holds ONE instance |
 | Same shape, each item linking to its own page | Entries of a collection |
 
 Count content levels, not DOM nodes. Component props nest at most three levels; a deeper subtree
@@ -220,7 +220,7 @@ field itself.
 | Pricing | Calculator | Range sliders with listeners, a live total in `<output>`, no submit |
 | Conversion | CTA band | Full-width high-contrast band, one heading, at most one sentence, one or two buttons, no inputs |
 | Conversion | Newsletter | A form with exactly one `type="email"` input, a consent line, a mail-provider action URL |
-| Conversion | Lead capture | Copy and bullets beside a multi-field form; fieldsets with Next and Back for multi-step |
+| Conversion | Lead capture | Copy and bullets beside a multi-field form; fieldsets with Next and Back for multi-step (`step` fields) |
 | Conversion | Contact | `mailto:` and `tel:` links by label, a form, a map iframe, hours |
 | Conversion | Popup | A hidden `role="dialog"` shown on a timer, scroll or mouse leave |
 | Listing | Blog index | `<article>` cards with image, heading link, `<time>`, excerpt; a shared href prefix |

package/dist/skills/bettercms/references/editor-chrome.md

@@ -82,6 +82,10 @@ Navigation, footer and dialogs live in the Global Layout (`get_layout`, `update_
 `get_next_steps` reports `chrome-duplicated`, declare the element in the Layout and push; the page
 copies are stripped for you. Never delete them by hand, and never give them dock chrome.
 
+A Global field with `overridable: false` and a `lockReason` is not offered on a page: a page write
+of it answers 403 **LAYOUT_FIELD_NOT_OVERRIDABLE** with the reason. A page value written earlier is
+kept but the Global value renders; `get_layout` scope page lists it under `shadowed`.
+
 ## Acceptance
 
 Read back with `get_content_model`, `get_page` or `get_component`. Done means `get_next_steps`

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

@@ -48,9 +48,10 @@ change it safely.
 
 For a complex one-off component, keep the working code and expose only an intentional prop
 contract. A nested child is edited through a `slot` prop or its own instance; the edit must
-address the child instance, never the parent definition. A `slot` holds exactly one nested
-component; for several heterogeneous children use the section's ordered children. Prevent
-circular nesting.
+address the child instance, never the parent definition. A `slot` holds one nested
+component, or a list of them with `config.multiple`; a fixed set of different children is the
+section's ordered children. A write that would nest a component inside itself is refused
+(`component_cycle`).
 
 ## Forms: the rules
 
@@ -127,7 +128,7 @@ The pipeline with the code that enforces each hop.
 
 ### 2. Field types and server checks
 
-Thirteen types exist (`src/lib/validation/schemas/forms.ts:61`, `:62`, `:65`). No file upload.
+Thirteen input types exist (`src/lib/validation/schemas/forms.ts`), plus `step`, a divider. No file upload.
 
 | Type | The server checks |
 |---|---|
@@ -140,6 +141,7 @@ Thirteen types exist (`src/lib/validation/schemas/forms.ts:61`, `:62`, `:65`). N
 | `url` | Starts with `http://` or `https://` |
 | `date` | `YYYY-MM-DD` |
 | `checkbox`, `hidden` | Nothing beyond `required` |
+| `step` | Nothing: a divider is never required and never submitted; a value sent under its key is refused with rule `step` |
 
 Any field with `required` is checked for presence. Every value must be a plain value or a flat
 list of them; a nested object is refused with rule `scalar`. Each refusal is
@@ -159,6 +161,16 @@ Rules:
 - Read `issues[].field` and `issues[].rule` to fix a refused submission; retrying unchanged returns
   the same refusal.
 
+#### Steps
+
+A multi-step form is one form with `step` fields in `fields`: `{ key, type: "step", label }` opens
+a page named `label`, and the fields before the first `step` are page 1. A step takes only `key`
+and `label` (`step_has_input_keys`), needs a field after it (`step_empty`), and a form has at most
+ten (`step_limit`). The visitor sees one page at a time with Back and Next, and the form posts
+once, at the end, as one submission whose body never carries a step key. Without JavaScript every
+page shows at once, as one long form. Map a source form's `fieldset` pages, or a "Next" button that
+only reveals the next group, to `step` fields; keep one `required` per real question, not per page.
+
 ### 3. MCP versus dashboard
 
 | Operation | Where |

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

@@ -129,8 +129,8 @@ for a reader before calling a site wired.
 
 Read it through one of those, the converted-site helper (`bcms`, `bcmsRows`, `bcmsImage`) or
 `publishedEntry(slug)`. Never hand-write a parser of the file: each row holds its field values
-under `data` (`row.data.title`), so code that reads `row.title` gets `undefined` and renders its
-fallback on every publish. An editable image is `bcmsImage(page, path, importedImage)`: the bare
+under `data` (`row.data.title`), so code that reads `row.title` gets `undefined` and the page shows
+its in-code copy after every publish. For an editable image call `bcmsImage(page, path, importedImage)`: the bare
 import with only a stamp never shows a published image on a route the app renders. An old
 `src/utils/bcms.ts` with `pageEntry()` is that parser: replace its reads with `publishedEntry`.
 

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

@@ -38,11 +38,11 @@ webhook. Use the project's webhook secret from the dashboard (the package docs n
 
 | Export | Use |
 |---|---|
-| `BcmsBlocks` | Render a block tree; pass `components` from `readComponents()` |
+| `BcmsBlocks` | Render a block tree; pass `components` from `readComponents()`. A block outside its `window` is not rendered, read against `now` (default: render time); `showScheduled` draws it marked `data-bcms-window`, for a draft preview |
 | `readComponents()` | Component definitions from `bcms-content.json` |
 | `BcmsField` | `path`, `kind` (`richtext`/`image`), `as`; server-safe |
 | `BcmsButton` | A `button` field: `path`, `value`, `className`; one `<a>` with `data-variant` / `data-size` for your CSS; server-safe |
-| `sectionRootAttrs(block)` | Spread on a section root your own code renders: `data-bcms-block`, `data-bcms-style` and the block's style ([components.md](components.md) §5) |
+| `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)) |
 | `buildMetadata(page, siteDefaults, location?)` | Next `Metadata` from native SEO fields |

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

@@ -79,6 +79,20 @@ 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.
 
+### Reading `get_deploy_status`
+
+- `release` is the newest release: `id`, `sha`, `status`, `phaseMarks`, `error`, `createdAt`.
+  While an uploaded build is ingested or released the state is `building`, `release.sha` is the
+  new sha and `lastLiveSha` the old one. Sending the live sha again does nothing. A failed deploy
+  has `release.status` `failed` and its `error`.
+- `held` means the release waits until the hold is cleared; `held.by` is `staff`, `archived` or
+  `no-subdomain`.
+- `slot` is where the bytes are: `current` is production, `staging` the staging handle.
+  `productionSha` is what production serves. `awaitingPromote: true` is a build that is verified
+  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.
+
 ### Deploy to Vercel or Netlify
 
 To serve a `managed` or `hybrid` site from the owner's own Vercel or Netlify account, call
@@ -156,6 +170,7 @@ for a content value the sync got wrong is §4.
 | Notify another system of an event | Event webhooks, `list_webhooks` / `create_webhook`: `content.publish`, `content.unpublish`, `content.stage_changed` (workflow stage), `content.created`, `content.updated`, `content.deleted` and `deployment.triggered`; HMAC-SHA256 signed in `X-BetterCMS-Signature`; payloads carry ids, never content. The signing `secret` is returned ONCE, on create. A receiver that writes back on `content.updated` loops unless it skips its own writes. Per-subscription payload filters: dashboard | You |
 | Send form submissions somewhere | Per-form integrations: Google Sheets, Slack, a webhook, email | Dashboard only |
 | Go live or retire at a time | `scheduledAt` (publish a draft at a time; needs publish permission) and `unpublishAt` (return a published row to draft) on `update_content_entry` and `update_page`; `null` cancels either. Campaigns: `publish_campaign` takes both | You. An edit that omits `scheduledAt` CANCELS the pending publish, so resend it with every edit before it fires; omitting `unpublishAt` never cancels it |
+| Show one section only for a period | `window` `{ from?, until? }` on a page block (`update_page` `blockJson`) or on a Layout Section (`update_layout` `add-section`, `update-section`). Shown from `from` until `until`; each is an ISO 8601 datetime with an offset (`2026-11-27T00:00:00+01:00`), stored as UTC, and either may be left out. `null` clears it. Refusals: `invalid_window` (no offset, or not a date), `window_inverted` (`from` not before `until`), `window_in_component` (inside a component's `blockJson`: put it on the placement), `window_in_entry` (on a block inside an entry's sections value: put it on the page block or Layout Section that shows the entry). A Section a page adds or customizes takes a window like a Global one | You. Outside its window the block is in no published output: the page, its Markdown, the delivery API and search. A draft preview draws it, marked. A page BetterCMS renders per request changes at the boundary; a static site catches up within about a minute, in place when a section goes and with a build when one appears. Site code that renders its own header ignores a Section's window |
 | Load many entries | `create_content_entries`: up to 200 drafts of one collection per call, each row `created` or `failed` (with `externalKey` also `updated` or `unchanged`, so a re-run is safe); then `publish_entries` | You |
 | React to edits made elsewhere | Poll `list_activity` with `since` set to the time of your last read (1–100 events per call) | You |
 | Generate or rewrite in bulk with a human gate | AI jobs: `list_ai_jobs`, `get_ai_job`, then `approve_ai_job` or `reject_ai_job` on the user's word | User approves |

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

@@ -102,7 +102,7 @@ Topics, FAQs, Testimonials) once. Drop any collection the source does not have.
 
 | Piece | Where it lives |
 |---|---|
-| Header, footer, announcement bar | Global Layout via `update_layout`. Never a page section. Footer link columns are a repeater of groups; the newsletter box points at a form |
+| Header, footer, announcement bar | Global Layout via `update_layout`. Never a page section. Footer link columns are a repeater of groups; the newsletter box points at a form. A bar or promo that runs for a period takes a `window` on its Section, and a seasonal band one on its page block ([publishing.md](publishing.md) §6) |
 | Company name, address, phone, social profiles | One place in the Global Layout, read by the footer and the contact page. Site JSON-LD repeats it once in `siteSchema` (`update_seo`) |
 | Cookie consent | A third-party consent tool stays code. Report it; do not rebuild it as content |
 | 404, legal, thank-you pages | Static pages in a `System` Content sidebar folder. Thank-you pages are noindex |
@@ -126,7 +126,7 @@ every entry and are not repeated in the tables. SEO fields are never listed.
 | One or many other entries | `reference`, `multi-reference`. A missing target is refused on write |
 | Call to action | `button` (label and link in one value). A bare link is `link`; also `email`, `phone` |
 | Date, date and time | `date`, `datetime`. Keep the zone as a `text` IANA name beside it when the site shows times |
-| A spec or comparison table | `repeater` of label and value rows. Models have no typed table field |
+| A spec or comparison table | `repeater` with one field per column (any field type) and `ui.layout: "table"`. There is no separate table field type |
 
 An external system's id (`"store_product_id"`, `"ats_job_id"`, `"feed_id"`, `"lms_course_id"`)
 is a `text` field kept as migration metadata and locked: `readOnly: "developer"` with a
@@ -194,7 +194,7 @@ collection-wide default in `collectionSchemaTypes`. Never a self-serving `Aggreg
 ### Forms
 
 Thirteen field types: `text`, `textarea`, `email`, `phone`, `number`, `url`, `date`, `select`,
-`radio`, `checkbox`, `checkboxes`, `consent`, `hidden`. No file upload, so CVs, floor plans and
+`radio`, `checkbox`, `checkboxes`, `consent`, `hidden`, plus the `step` divider for multi-step forms. No file upload, so CVs, floor plans and
 attachments go to the external system. Payment details never go in a form. Submissions land in
 the inbox; an editor turns one into an entry. Full pipeline:
 [forms-and-interactions.md](forms-and-interactions.md).
@@ -208,6 +208,19 @@ the inbox; an editor turns one into an entry. Full pipeline:
 - Every collection has a `urlPattern`; every changed URL has a 301.
 - Structured data is built from visible fields, with the type its catalog names.
 
+### Built-in sections
+
+The section library ships 23 platform blueprints in 17 families, so a standard band needs no new
+component: Hero, Feature grid (three, two, bento), Feature rows, Steps, Timeline, Stats, Logo cloud,
+Testimonial (quote, three cards), Team, Case study, Comparison, Pricing, FAQ, Call to action,
+Capture (newsletter band) and Listing (latest, related). Read one with `list_components`; inline its
+`blockJson` as a `section` block for a one-off band, or copy it with `create_component` `from:
+"builtin:<key>"` for a recurring one (see [components.md](components.md)). Two ship unbound on purpose: the Capture form has no form until you
+set its `form` prop, and both Listing layouts list the page's own entries until you give them a
+`source`; each shows its empty text meanwhile. Not available as a section, so build it in the repo
+or leave it out: mega menu, docs sidebar, cookie consent, exit intent, store locator, map, billing
+toggle, countdown and anything commerce.
+
 ## Portfolio website
 
 Use this when the primary job is to show selected work and make an individual or small studio credible. First determine whether the work is private, client-approved, dated, or still under embargo.
@@ -674,7 +687,8 @@ countdown.
 | Sponsors | `"logo"`, `"tier"` `select`, `"website"` `link` |
 
 - **Chrome:** header with a tickets button; an announcement bar whose countdown end is one
-  `datetime` with its zone. Never migrate a countdown that resets per visitor.
+  `datetime` with its zone, and whose Section `window` ends with it. Never migrate a countdown
+  that resets per visitor.
 - **Lists:** a `collection` block with `source` sorts by `"starts_at"`, but its filter values
   are fixed: none means "today". Upcoming and past lists, and an agenda grouped by day and
   track, are the site's code filtering on `"starts_at"`. State that in the report; do not fake

package/dist/skills/bettercms/references/worked-examples-advanced.md

@@ -484,10 +484,24 @@ the attributes. What it writes:
 - Without the definitions passed to the renderer, every instance draws empty: check that before
   debugging a card.
 
-Not available today: a slot with several children. A `slot` prop holds one instance, so "a column
-of mixed blocks" is a `columns` block, not a slot. A tab icon (a tab has a label only) and a
+A slot can hold several children. Give the `slot` prop `config: { multiple: true }` and point its
+target at a container's child list (`props.children` on a `section`, `props.columns.<n>` on a
+`columns` block); a placement then lists the children, each a published component of this project:
+
+```json
+{ "type": "component", "id": "tour-cards", "props": { "componentId": "<card grid id>", "overrides": {
+  "cards": [
+    { "componentId": "<tour card id>", "overrides": { "title": "Plan" } },
+    { "componentId": "<stat id>", "overrides": { "value": "3.4x" }, "style": { "hideOn": ["mobile"] } }
+  ] } } }
+```
+
+A fixed layout of different blocks that the editor never reorders is still a `columns` block, as
+in the tabs above. Rules and refusal codes: [components.md](components.md).
+
+Not available today: a tab icon (a tab has a label only) and a
 "first open tab" setting. Per-column widths: columns are equal, and `gap` is a whole number of
-pixels, not a named size. Per-breakpoint values on any of these.
+pixels, not a named size. Per-breakpoint sizes are not available; `style.hideOn` (`["mobile"]`, `["tablet","desktop"]`; never all three) hides a block at up to two breakpoints, under 768, 768-1023 and 1024 and up, as `display:none` that keeps it in the HTML.
 
 ## Checks
 

package/dist/skills/bettercms/references/worked-examples.md

@@ -94,7 +94,8 @@ Schema (`create_page` `fields`, or one `add_field` with `pageId` per field):
   { "key": "hero_secondary", "label": "Secondary button", "type": "button" },
   { "key": "hero_image", "label": "Background image", "type": "image",
     "helpText": "Fills the whole band behind the text. Use a photo at least 2560 px wide." },
-  { "key": "hero_rating", "label": "Rating", "type": "number", "config": { "min": 0, "max": 5, "step": 0.1 } },
+  { "key": "hero_rating", "label": "Rating", "type": "number", "config": { "min": 0, "max": 5, "step": 0.1 },
+    "ui": { "control": "rating" } },
   { "key": "hero_rating_label", "label": "Rating source", "type": "text", "richText": false }
 ]
 ```
@@ -258,10 +259,9 @@ Bound template (first card):
 - The icon `<svg>` is not bound: no field is read from text inside an SVG. The name is edited in
   the side panel and the template turns it into the sprite reference.
 
-Not available today: an `icon` FIELD type with a picker over a named icon set. In a model or
-page field a sprite icon is a plain name; only an inline SVG stored as an `image` with
-`media: "icon"` gets the editor's icon picker. A component prop does have the `icon` type: a
-BetterCMS icon name or an image ([components.md](components.md) §1).
+To make the icon editable, add a field of type `icon`: its value is a BetterCMS icon name or an
+uploaded icon, and a name off the set is refused. A component prop of type `icon` takes the same
+value ([components.md](components.md) §1). An inline SVG stays an `image` with `media: "icon"`.
 
 ## 3. Pricing plans with a comparison table
 
@@ -446,10 +446,19 @@ Bound template (the Growth card and one comparison row; `pricing-01` is the inst
 - A comparison written as prose instead belongs in a `richtext` prop as a Portable Text `table`
   ([portable-text.md](portable-text.md)); then the wrapper of that one value is the bound element.
 
-Not available today: typed table columns (money, boolean) and a per-cell type; every cell is text
-or one sub-field type for the whole column. Rows keyed to plan ids, and a field only a developer
-can change. Offer markup: no JSON-LD is built from prices. Paste it as `schema` on `update_page`
-when the page needs it. A fourth plan in the comparison is a new sub-field, a schema change.
+A typed table is available on both sides. On a component each `table` column is one sub-field
+with its own type (`number`, `boolean`, `url`, ...), as `monthly` and `ctaUrl` are above. On a
+model it is a `repeater` (stored as an `array` with `config.zones.repeatable.fields`): one field
+per column, of any field type, `minItems` / `maxItems` on the repeatable zone, and
+`ui.layout: "table"` to edit the rows as a grid. To key rows to plan ids, give the model a `text`
+column with `unique: true`. A value only a developer may change is a model field with
+`readOnly: "developer"` and a `lockReason`.
+
+Not available today: a per-cell type (a column has one type for every row), and a caption,
+footnotes or row groups as parts of the table (model them as fields beside it, as `group` and
+`fineprint` are here). Offer markup: no JSON-LD is built from prices. Paste it as `schema` on
+`update_page` when the page needs it. A fourth plan in the comparison is a new sub-field, a schema
+change.
 
 ## 4. Testimonials kept as a collection
 
@@ -576,6 +585,10 @@ Bound template (the section's own values; one card shown):
   for every page that shows them. The picked list is changed in the side panel.
 - Draw the stars from `rating`; never store the glyphs.
 
+One chosen entry on a hosted page is a `collection` block, not a prop: `source: { modelId }`,
+`pinnedIds: ["<entry id>"]`, `limit: 1` and `cardComponentId` naming the card that draws it. Pinned
+entries come first, so the limit keeps exactly that one.
+
 Not available today: a component prop that references entries (there is no reference prop type; it
 would save and render nothing). A listing chosen by tag or filter on a route the repo's code
 renders: the `collection` block with `source`, `filters` and `sort` is drawn by the hosted

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/mcp",
-  "version": "0.69.0",
+  "version": "0.70.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.27.0",
+    "@bettercms-ai/sdk": "^1.28.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.3.6"
   },