@bettercms-ai/mcp 0.67.3 → 0.68.1

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
@@ -193,6 +196,20 @@ A code-built site ships only what its templates draw, whatever the page's `block
      the page: the anchor carries `data-bcms-button="<key>"` and `get_binding_report` lists no
      unmatched path for it. The button field is added by that build and starts from the pair's
      label and link.
+- **Read a published value where the app renders the page** (the fix a publish that fails with
+  "Published, but this page's code doesn't read this field yet: `<key>`" names). On a route the
+  site's app renders, a stamp (`data-bcms-field`, a `bcmsBindings` entry) only says where a field
+  IS; the page shows a publish only when its code READS the value. In code, on a branch:
+  1. Read through the helper the conversion wrote (`bcms`, `bcmsRows`, `bcmsImage`, `bcmsLayout`
+     from `src/bcms-content.ts`) or the SDK's `readPublishedContent` / `publishedEntry`. Never read
+     a row of `bcms-content.json` by hand, and never bundle the file (`import`, `import.meta.glob`).
+  2. An image the page imports and passes on (`src={heroImage}` beside
+     `bcmsBindings={{ image: "<key>" }}`): pass `src={bcmsImage(<page snapshot>, "<key>", heroImage)}`.
+     The import stays the fallback; a published image is served from the copy BetterCMS places
+     beside the app. `npx @bettercms-ai/convert` makes this edit for every such call site.
+  3. Keep the hard-coded copy as the fallback argument, so a build with no content renders as today.
+  4. Open a pull request. After it is merged and the site rebuilt, publish the field again: the
+     toast reads "Live".
 
 ## 6. Preview source
 

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/frameworks.md

@@ -127,6 +127,13 @@ generated reader. A build that fetches the snapshot and never reads it still ren
 hard-coded copy, so every edit saves, publishes and changes nothing on the page. Grep the source
 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
+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`.
+
 Build with the repo's own `build` script (`pnpm build`, `bun run build`), never the framework CLI
 directly: a repo's script often adds a type check or a post-process step the CLI skips.
 

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

@@ -82,6 +82,9 @@ Rules:
   a live fetch would turn pages into dynamic routes, and a static export silently leaves them out
   of `out/`.
 - A preview build that must read live sets `BETTERCMS_PREVIEW=1`.
+- On a BetterCMS build the platform's own `bcms-content.json` is already in the project root.
+  `bettercms-snapshot` keeps it and `getContent` reads it: one file feeds `getContent`, `readPages`,
+  `readForms` and `readComponents`.
 - Draft mode and the revalidation route need a server; a static export has neither. Content
   changes reach a static site only by rebuilding it.
 

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.1",
   "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.26.2",
+    "@bettercms-ai/sdk": "^1.26.3",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.3.6"
   },