@bettercms-ai/mcp 0.72.0 → 0.72.2

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

@@ -88,6 +88,33 @@ import BcmsSections from "@bettercms-ai/astro/components/BcmsSections.astro";
   too until the list names one of the page's slots; from then on it is a removed section. Write
   a slot bare only when the page already places that bind (`get_page`), otherwise `code:`.
 - No snapshot (a local build, the API down): every slot renders in source order, untouched.
+
+**A page that only draws a view.** Where the page file is a shell (`<HomeView locale="en" />`,
+alone or inside its layout) the sections are written in the view, and `--sections` wraps them
+there: it follows the import (relative, or a `paths` alias the repository's own tsconfig or
+jsconfig declares, index files included) up to three components down, to the first file that
+writes two or more sections or writes its run inside a layout. One view often serves several
+pages (`/` and `/fr`), so the view cannot name the page. Each page hands it down, and the view
+reads it:
+
+```astro
+<!-- src/pages/fr/index.astro -->
+<HomeView locale="fr" bcmsPage="fr" />
+
+<!-- src/views/HomeView.astro: `bcmsPage?: string` joins its Props -->
+<MainLayout>
+  <BcmsSections page={Astro.props.bcmsPage ?? ""}>
+    <Fragment slot="hero"><HeroSection title={copy.hero.title} /></Fragment>
+    …
+  </BcmsSections>
+</MainLayout>
+```
+
+Each page then follows its own CMS page's list through the one set of slots. A route that hands
+the view no page (the CMS has none for it yet) renders the source order. A slot is bare only
+when every page drawing the view places that bind. A dynamic route's view (`blog/[id].astro` →
+`BlogPostView`) is wrapped the same way with `template`. Write it by hand in this shape when the
+codemod refuses the view ([componentize.md](componentize.md) §5).
 - The list is the published snapshot's, or the draft's when the Visual Editor frames a
   server-rendered page (`prerender = false`). `blocks={…}` gives it yourself.
 

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

@@ -140,6 +140,11 @@ npx @bettercms-ai/convert --sections --root .
 npx @bettercms-ai/convert --verify-styles --root .        # must report no style edits
 ```
 
+A page file that only draws a view component (`<HomeView locale="en" />`) is wrapped in the
+view's file, where its sections are written; the dry run names that file per page, and the page
+itself only gains the prop that tells the view which page it is ([astro.md](astro.md),
+[next.md](next.md)). A lone component that is itself one section is wrapped in the page.
+
 A page it leaves alone keeps rendering as before, and is listed with one of these:
 
 | Reason | The page | What you do |
@@ -154,6 +159,9 @@ A page it leaves alone keeps rendering as before, and is listed with one of thes
 | `DIALECT_UNSUPPORTED` | Markdown, MDX or HTML | Nothing: the body is one `document` field |
 | `NAME_TAKEN` | Already uses the name `BcmsSections` for something else | Rename that, run again |
 | `SDK_REQUIRED` | The repo's SDK predates the component | Add `--add-sdk`, install, run again |
+| `VIEW_IMPORT_UNRESOLVED` | Draws one component, and its import names no file: an alias no tsconfig or jsconfig of the repository declares (one inherited through `extends` is not read) | Declare the alias in the config's own `compilerOptions.paths`, or import the view by a relative path; run again |
+| `VIEW_DEPTH_EXCEEDED` | Its sections are more than three components below the page | Wrap by hand in the file that writes them, and pass the page down ([astro.md](astro.md), [next.md](next.md)) |
+| `VIEW_SHARED_INCOMPATIBLE` | Draws a view another page draws too, and the CMS names the view's sections differently on the two (or one is a page and the other a collection's item template, in Astro) | Give each page a view of its own, or make the two CMS pages place the same binds, then run again |
 
 The by-hand markup is in [astro.md](astro.md) and [next.md](next.md), and it follows the rules of
 [animation.md](animation.md) §10: slot tags around sections you do not edit, no new element. On

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

@@ -32,6 +32,13 @@ defaultValue? }`.
 - **A `button` prop is one unit.** Its value is `{ label, href, variant?, size?, arrow?, icon?,
   newTab? }` and its `target.path` is `props` on a `button` block. For a new component never
   declare a label prop plus a url prop: the two drift apart on the first edit.
+- **A button the site's own script handles has no href.** Its value is `{ label, action: "code",
+  variant?, size?, arrow?, icon? }`: a `<button type="button">` that opens a dialog, accepts
+  cookies or starts a tour. The label and the look are edited; the click stays the site's.
+  `href`, `newTab` and `rel` beside `action: "code"` are refused, and a value with neither an
+  href nor the action is refused as before. Setup derives these as button fields on a new
+  import. A control of the page itself is never one: a menu or theme toggle, a carousel arrow, a
+  dialog's close, an accordion or tab trigger, a copy button, a pagination step.
 - `target.blockId` + `target.path` must point at a real block and property inside the
   component's own `blockJson`. Why: rendering copies each prop's value to that target; a target
   that does not exist renders the default and the edit goes nowhere.
@@ -227,7 +234,10 @@ adding or spacing one section is the recipe in [publishing.md](publishing.md).
   `BLOCK_ID_ONLY`, …) its block style by hand, confirm with `--verify-styles`, push and release.
 - **A `button` field renders with `BcmsButton`** (`path`, `value`): one `<a data-bcms-button>`
   carrying `data-variant` and `data-size`, so every look control (style, size, arrow, icon, new
-  tab) applies on the canvas and on publish.
+  tab) applies on the canvas and on publish. A value with `action: "code"` renders
+  `<button type="button" data-bcms-button>` with the same children and no href: attach your
+  handler to it as before. A publish writes its label and look and never an href, a target or a
+  rel, and never turns it into an anchor.
 - **A button's looks are the ones the site already has.** Each release measures the built pages
   and keeps the project's Button family equal to the looks found there. Style offers those looks
   and no others, and a publish paints a pick with the site's own classes. Never write CSS for a
@@ -251,6 +261,12 @@ adding or spacing one section is the recipe in [publishing.md](publishing.md).
   | Ghost | No fill and no border, padded like a button or filled on hover. |
   | Text Link | A plain link the site styles as a call to action. Menu and footer links and links in copy are not looks. |
 
+  What counts as a button is one rule for the family and for the fields: what the site names one
+  (`btn`, `button`, `cta`, `role="button"`), or what its stylesheet paints as one (a fill or a
+  border of its own). Two looks paint nothing at rest and still count: a ghost, by its own padded
+  box, and a text link drawn as a row that underlines. In a menu those two count only beside a
+  painted button.
+
   A light and a dark rendition, a hover or disabled state, a size, and one paint spelled in two
   sets of classes are all ONE look. Two looks left with one role are told apart in words from
   their paint ("Outline on dark", "Pill Outline"). A role once given stays: a look added later

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

@@ -191,6 +191,28 @@ form is named for what it is for: its `aria-label`, its one legend, a heading in
 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/next.md

@@ -103,6 +103,34 @@ A page with its own data function passes it in, and the list joins the props it
 `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`.

package/dist/skills/bettercms/references/portable-text.md

@@ -76,7 +76,7 @@ names the field accepts.
 | decorators (span `marks`) | `strong`, `em`, `underline`, `strike-through`, `code`, `highlight` | `b`, `i`, `u`, `s`, `code`, `mark` |
 | annotations (`markDefs`) | `link` {href, target, className}; `styled` {tag, className, attrs} | `link`/`internalLink`; always |
 | `listItem` | `bullet`, `number`, `check` | `ul`, `ol`, `checklist` |
-| block objects | `bcmsDivider`; `bcmsCode` {code, language}; `bcmsBlock` {schemaKey, schemaLabel, fields}; `table` {rows} | `p`; `pre`; `image`/`embed`/`columns`; `table` |
+| block objects | `bcmsDivider`, `pullQuote` {quote, name, role?, link?}; `keyTakeaways` {title?, points}; `bcmsCode` {code, language}; `bcmsBlock` {schemaKey, schemaLabel, fields}; `table` {rows} | `p`; `ul`; `pre`; `image`/`embed`/`columns`; `table` |
 | inline objects | `bcmsMention` {label} | always |
 
 - **Keys**: every block, span, markDef, row and cell has `_key` matching `^[A-Za-z0-9-]{1,32}$`,
@@ -85,16 +85,22 @@ names the field accepts.
   block. Every markDef is referenced by at least one span.
 - **Lists are flat**: a list item is a normal block with `listItem` and `level` (1 = top). Never
   nest blocks inside a list container. A `check` item carries `checked: true|false`.
+- **Pull quote**: `{_type:"pullQuote", _key, quote, name, role?, link?}`; `quote` and `name` are
+  strings, `link` is a URL (or a link object with `href`) the name links to. A `pullQuote` without
+  string `quote` and `name` is refused on write. Renders `<figure data-rt="pullquote">`.
+- **Key takeaways**: `{_type:"keyTakeaways", _key, title?, points}`; `points` is an array of plain
+  strings, one per bullet. More than 8 points or a title over 40 characters is refused on write,
+  by code and path. Renders `<aside data-rt="takeaways">`.
 - **Tables**: a cell holds blocks in `content`, not a string. `header: true` marks a `<th>` cell;
   `head: true` puts a row in `<thead>`.
 - **`styled`** carries a site's own inline markup; `tag` is one of `span`, `small`, `sup`, `sub`,
   `kbd`, `abbr`, `time`, or a decorator tag (`strong`, `em`, `b`, `i`, `u`, `s`, `mark`, `code`, …)
   that carries a class. A `link` keeps its class as `className`.
 - **Top-level `_type`** is one of `block`, `bcmsBlock`, `table`, `bcmsCode`, `bcmsDivider`,
-  `bcmsMention`. A name outside that list is refused on write, by name and `_key`, because the
-  block would disappear from the live site. The refusal is **top level only**: a foreign mark
-  passes and its text renders unmarked; a foreign inline child passes and renders nothing. Check
-  those yourself.
+  `bcmsMention`, `pullQuote`, `keyTakeaways`. A name outside that list is refused on write, by
+  name and `_key`, because the block would disappear from the live site. The refusal is **top level
+  only**: a foreign mark passes and its text renders unmarked; a foreign inline child passes
+  and renders nothing. Check those yourself.
 
 A paragraph with a bold word and a link:
 

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

@@ -501,7 +501,7 @@ 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 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.
+pixels, not a named size. Per-breakpoint sizes are not available; `style.hideOn` (`["mobile"]`, `["tablet","desktop"]`) hides a block at those breakpoints, under 768, 768-1023 and 1024 and up, as `display:none` that keeps it in the HTML; all three hides it on the page, and no published page, Markdown twin or search index carries it.
 
 ## Checks
 

package/package.json

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