@bettercms-ai/mcp 0.67.3 → 0.68.0

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

@@ -204,3 +204,6 @@ still renders hard-coded copy is not connected. Client components never receive
 - No public secrets, wrong media hosts, unscoped instance ids or hard-coded shadow values.
 - `get_binding_report` for each route is clean, and one value of each bound kind opens the right
   editor in the Visual Editor.
+- `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").

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

@@ -87,10 +87,11 @@ Hero / Split
 Expose variants and style tokens, never raw class names, CSS strings or HTML.
 
 **Name props from the code, not the copy.** An import labels a prop by its role (`Text`,
-`Heading`) with its copy as help text (`e.g. "49"`), and older imports by the copy itself (`.00`).
+`Heading`) and writes its help from that role, and older imports by the copy itself (`.00`).
 Read the section's source and use its own names: `pricing.starterKit.cents` → `Cents`,
-`billingFrequency` → `Billing frequency`. Give every prop help text showing its shape
-(`e.g. "USD / monthly"`). Apply both in one `update_component` call: `propLabel` and
+`billingFrequency` → `Billing frequency`. Where you know more than the role does, write the
+prop's help text: what it is for, where it shows, any limit ("Shown after the price, such as per
+month."), never its label or value again. Apply both in one `update_component` call: `propLabel` and
 `propHelpText`, keyed by prop key. Repeated cards (plans, features, team members) are ONE `table`
 prop whose rows are the cards (`Plans`: Name · Description · Price · Cents · Billing frequency ·
 Features · Button), never a set of props per card, so an editor opens one plan at a time and can

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

@@ -20,6 +20,9 @@ defaultValue? }`.
 - `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.
+- Every prop takes `helpText` and the component a `description` ("Hero with a heading,
+  supporting text and two buttons."). Leave them out and the platform writes them; write your
+  own by the rules in [content-modeling.md](content-modeling.md) ("Writing help text").
 - `update_component` replaces the whole `props` array. Read with `get_component`, change, write
   all props back.
 - `select` needs `config.options`; `slot` holds one nested component instance; `form` holds one

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

@@ -117,12 +117,39 @@ fail, because the next redesign makes them lie.
 
 Short labels named for what the editor sees: Heading, Body, Primary button, Label, Link, Image,
 Alt text — or the name the site's code already uses (`cents` → Cents), never the copy itself
-(`.00`). Every field gets help text showing its shape (`e.g. "49"`). Group by what renders
-together, not by the DOM or the source file: core content first, optional appearance second, technical fields hidden. Help text states an effect ("Shown below the
-heading on this page"). Repeatable items need a meaningful preview label (the FAQ question, the
+(`.00`). Every field gets help text (below). Group by what renders
+together, not by the DOM or the source file: core content first, optional appearance second, technical fields hidden. Repeatable items need a meaningful preview label (the FAQ question, the
 button label), reorder, and stable item ids. An empty optional field removes its element without
 leaving a gap; a long value wraps, and clamps only where the design intends it.
 
+### Writing help text
+
+Every field, prop, component, collection and Global section carries help an editor reads under
+its name: `helpText` on a field or prop, `description` on a component, a collection and a Layout
+Section (`update-section`). Write it the way a Sanity schema writes `description`:
+
+- **Purpose, placement, constraint.** What it is for, where it shows, and a limit when one is
+  real. One or two sentences, plain words, sentence case.
+- **Never the label or the value again.** `e.g. "Starter Kit"` under an input holding "Starter
+  Kit" tells the editor nothing, and the API refuses help that echoes the value. An example may
+  follow a real sentence when it shows a format.
+
+| Element | Good | Bad |
+|---|---|---|
+| Hero heading | The page's main heading. One per page; keep it under about 60 characters. | Heading |
+| Button label | Text on the button. Two to four words works best. | e.g. "Get started" |
+| Meta description | Shown in search results under the page title. Aim for 120–160 characters. | The meta description. |
+| Logo | Logo shown in the header. An SVG or transparent PNG works best. | Image |
+| Component | Hero with a heading, supporting text, two buttons and an image. | Hero |
+
+Leave it out and the platform writes a line from the element's role, and says so
+(`helpText: { source: "auto" }` in the response, `helpSource: "auto"` on the stored field).
+Text you send is stored as yours (`helpSource: "agent"`) and is never rewritten; `editor_setup`
+rewrites only its own lines and never a person's. `get_next_steps` lists anything left without
+help as `help-text-missing`, and `get_binding_report` and `get_site_composition` carry the
+coverage as `help`: under 100% is a finding. Write your own line wherever the generated one
+is generic and you know more: the audience, the tone, who signs off, what breaks the layout.
+
 ## 6. Changing a schema safely
 
 A schema write alone is not a release. Before one, read the model with `get_content_model`, a few

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

@@ -72,7 +72,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) |
-| 3 | Editor contract: field types, labels, validation, Portable Text accept lists, nested groups | [portable-text.md](portable-text.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) |
 | 6 | Behaviour: forms, links, menus, accordions, modals, consent, custom code | [forms-and-interactions.md](forms-and-interactions.md) |

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

@@ -17,7 +17,7 @@ each report was generated:
 
 | Read | Tells you |
 |---|---|
-| `get_site_composition` | Which pages are made of sections, and which components they use |
+| `get_site_composition` | Which pages are made of sections, and which components they use; `help`: how much of the schema carries help text, and what does not (under 100% is a finding) |
 | `get_binding_report` | Per route: `mode` (`declared` or `text-match`), `coverage.pending`, and `refreshReason` when there is no current report |
 | `list_seo_issues` | Native SEO problems per page |
 | `get_component_readiness` | Per component: validation and Output state |

package/package.json

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