@bettercms-ai/mcp 0.84.4 → 0.85.0

package/dist/skills/bettercms/SKILL.md

@@ -147,7 +147,7 @@ resources: `bettercms://skill/bettercms` for this file, and each reference under
 | Nuxt, SvelteKit, React Router, Vite: no adapter | [other-frameworks.md](references/other-frameworks.md) | neither `astro.config.*` nor `next.config.*`; `nuxt.config.*`, `svelte.config.*`, `react-router.config.*` | Nuxt, SvelteKit, React Router, Vite, createClient |
 | Rich text and field types | [portable-text.md](references/portable-text.md) | writing a richtext value; converting HTML or Markdown | rich text, Portable Text, richtext, HTML, Markdown |
 | Brand kit, tokens, fonts, logo, images, icons | [media-and-brand.md](references/media-and-brand.md) | design fidelity, alt text, a logo or favicon change | brand, tokens, fonts, logo, image, alt text, favicon |
-| Connect a vendor with a public API (jobs board, store, CRM, video): declare, approve, call, recipes | [integrations.md](references/integrations.md) | the user names Greenhouse, JobDiva, Shopify, HubSpot, Zoom, Apollo or any API; a 409 `integration_not_approved` | integration, API key, Greenhouse, JobDiva, Shopify, HubSpot, Zoom, Apollo, sync, vendor, token |
+| Connect a vendor with a public API (jobs board, store, CRM, video): declare, approve, call, recipes | [integrations.md](references/integrations.md) | the user names Greenhouse, JobDiva, Shopify, HubSpot, Zoom, Apollo or any API; a 409 "integration_not_approved" | integration, API key, Greenhouse, JobDiva, Shopify, HubSpot, Zoom, Apollo, sync, vendor, token |
 | Forms, menus, accordions, modals, consent | [forms-and-interactions.md](references/forms-and-interactions.md) | attaching or verifying a form; an interactive section | form, submission, Turnstile, modal, accordion, menu |
 | Languages, locale prefixes, translation, hreflang | [localization.md](references/localization.md) | the build serves `/fr`-style prefixes; `locale-unvarianted` in a binding report | language, locale, /fr, translate, hreflang, i18n |
 | SEO and AEO | [seo.md](references/seo.md) | meta, JSON-LD, sitemap, robots, redirects, AI crawlers, `list_seo_issues` | SEO, meta, JSON-LD, schema.org, sitemap, robots, OG image, redirect, 410, llms.txt |

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

@@ -9,6 +9,15 @@ Doctrine (what should be editable, the conversion loop): §11 and §13 of
 `bettercms://playbook/schema`, and the `convert_site` prompt. This is the template side. Rich-text
 values: [portable-text.md](portable-text.md). Adapter wiring and env: [frameworks.md](frameworks.md).
 
+## Contents
+
+- [1. Why the attributes matter](#1-why-the-attributes-matter) · [2. Bind the leaf](#2-bind-the-leaf-and-know-which-vocabulary-you-are-writing-in)
+- [3. Addresses](#3-addresses) · [4. Declared mode, publish, and the report](#4-declared-mode-publish-and-the-report)
+- [5. Preview strings (stega)](#5-preview-strings-stega) · [6. Classify an unfamiliar codebase](#6-classify-an-unfamiliar-codebase-before-binding-it)
+- [7. Edit-to-render test](#7-edit-to-render-test) · [Acceptance](#acceptance)
+- [Reading the binding report and the conversion receipt](#reading-the-binding-report-and-the-conversion-receipt)
+- [Editor setup, proposals and binding decisions](#editor-setup-proposals-and-binding-decisions)
+
 ## 1. Why the attributes matter
 
 A `data-bcms-*` attribute is the only thing that locates a stored value on a rendered page. Five

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

@@ -47,7 +47,7 @@ defaultValue? }`.
   a prop's help only for a format or unit, a place the canvas cannot show, a real constraint or
   a fallback (most props get none). Write your own by the rules in
   [content-modeling.md](content-modeling.md) ("Writing help text"): one short plain sentence,
-  under 90 characters, with no semicolon, no dash and no figure taken from the page.
+  of at most 160 characters, with no semicolon, no dash and no figure taken from the page.
 - A prop takes `showIf` (`{ match, rules: [{ field, op, value? }] }`): hidden until SIBLING props match. `op` is `eq`, `neq`, `in`, `isSet`, `notEmpty` or `empty`; the last three take no `value`, the first three need one. Props and model fields share all six, and a sub-field's `showIf` names its sibling sub-fields.
 - `object` holds ONE `{ childKey: value }` built from `config.fields` (required), like the model field `object`. Groups, tables and objects nest to 10 levels counting the prop; an 11th is refused `field_depth_exceeded`. Aim an `object` at `props` or at a key your component code reads, never at a text slot such as a heading's `props.text` (`prop_target_unrenderable`).
 - `datetime`, `slug`, `email`, `phone`, `json`, `location` (`{ lat, lng }`), `tags` (`string[]`), `rating` (0..`config.max`) and `code` (`{ language?, code }` or a string) hold what the same-named model field holds, and a placement's value is checked by that field's rules (`prop_value_invalid`). Like `object`, a `tags` or `code` prop never targets a text slot.

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

@@ -204,7 +204,7 @@ stored field. Text you send is stored as yours (`helpSource: "agent"`) and is ne
 
 Ask one question per field: does the editor need this line to type the right value? Write your
 own `helpText` (on a field or a prop) only for one of four reasons, written as one short plain
-sentence under 90 characters, with no semicolon, no dash and no figure taken from the page.
+sentence of at most 160 characters, with no semicolon, no dash and no figure taken from the page.
 
 | Reason | Good |
 |---|---|

package/dist/skills/bettercms/references/dock-input.md

@@ -1,6 +1,6 @@
 ---
 title: "Custom dock inputs"
-description: "When a field earns its own input in the editor dock, how to ask the user first, the input contract and protocol, the writes allowlist, the file layout, and the fallback guarantee."
+description: "When a field earns its own input in the editor dock, how to ask the user first, the input contract and protocol, the writes allowlist, the file layout, the fallback guarantee, and UI stored in the CMS (write/approve/validate/publish_dock_ui)."
 ---
 
 # Custom dock inputs
@@ -123,3 +123,91 @@ The stock control comes back whenever the input cannot run: an unknown name, inp
 the project, a build that failed, a frame that throws or misses `ready`. The value is unchanged
 and stays editable. So a custom input can only add to the dock, never take a field away from an
 author. Removing `ui.input` returns the field to the stock control at once.
+
+## 9. UI stored in the CMS (no repo push)
+
+The same input, or a panel, can live in the CMS instead of `bettercms/inputs/`. Use it when the
+site has no repo you can push to, or for a panel a section, a page or the Layout needs. The
+restraint ladder (section 1) and the user's yes (section 2) still come first.
+
+| Step | Tool | What happens |
+|---|---|---|
+| 1 | `write_dock_ui { name, scope, kind, target, source }` | saves a new DRAFT version; the same bytes again write nothing |
+| 2 | show the user the source and what it is for | wait for an explicit yes |
+| 3 | `approve_dock_ui { name, version, userApproved: true }` | approves that ONE version; a later write drops it |
+| 4 | `validate_dock_ui { name }` | the import allow-list, the size caps, a name clash; the build receipt |
+| 5 | `publish_dock_ui { name }` | validates again, then the dock serves that version |
+| — | `list_dock_ui { scope?, status? }` | every source, its status and the project's usage |
+
+- `name` is what `cms:<name>` imports resolve: a lowercase letter first, then letters, digits and
+  hyphens, at most 48 (`DOCK_UI_NAME_UNSERVABLE` otherwise: such a name could never build).
+  A name the repo also ships (`bettercms/inputs/<name>.tsx`) refuses `build.name_conflict`: rename one.
+- `source` is ONE `.tsx` file, at most 256 KiB, whose default export is the component (section 5).
+  It imports only `react`, `react-dom`, `@bettercms-ai/kit/*`, `@bettercms-ai/dock-input` and its
+  siblings as `cms:<name>`, which resolve to their PUBLISHED version. Anything else, or a computed
+  `import()`, refuses `build.import_denied` naming the import.
+- Limits per project: 64 sources and 4 MiB across their newest versions (`build.size_exceeded`).
+- `approve_dock_ui` without `userApproved: true` refuses `policy.confirmation_required`. A version an
+  agent wrote is approved by an agent only on a connection allowed to publish; otherwise it refuses
+  `policy.not_approved` (detail "self_approval") and a person approves it in the dashboard.
+- `publish_dock_ui` on a version nobody approved refuses `policy.not_approved`. On success it rebuilds
+  the project's dock UI release (the repo's inputs plus every published CMS source) and answers its
+  `release` key. A project with no site handle yet refuses `build.compile_error` (detail "no_site_handle"):
+  publish the site once, then publish again. A failed build leaves the stock control (section 8).
+
+One minimal example per scope. The `target` says what the UI is for.
+
+```
+// field: an input for one field (`kind: "input"`). Then set ui.input { name } as in section 2.
+write_dock_ui { name: "brand-swatch", scope: "field", kind: "input",
+  target: { modelId: "<model id>", path: "accent" },
+  source: "import { Button } from '@bettercms-ai/kit/ui'\nconst SWATCHES = ['#0f172a', '#2563eb', '#16a34a']\nexport default function BrandSwatch({ value, onChange, readOnly }) {\n  return <div>{SWATCHES.map((c) => <Button key={c} disabled={readOnly} aria-pressed={value === c} onClick={() => onChange(c)}>{c}</Button>)}</div>\n}" }
+
+// section: a panel beside one component's props
+write_dock_ui { name: "hero-checklist", scope: "section", kind: "panel",
+  target: { componentId: "<component id>" }, source: "export default function Panel({ document }) { … }" }
+
+// page: a panel on one page
+write_dock_ui { name: "launch-notes", scope: "page", kind: "panel", target: { pageId: "<page id>" }, source: "…" }
+
+// layout: a panel on the global Layout (header, footer)
+write_dock_ui { name: "nav-audit", scope: "layout", kind: "panel", target: {}, source: "…" }
+```
+
+### What each tool takes and answers
+
+The shapes are `@bettercms-ai/types` `dock-ui.ts`. A `source` row is `DockUiSource`: `{ id, name, scope, kind,
+target, headVersion, publishedVersion | null, status: draft | approved | published, approvedBy, approvedAt,
+buildReceipt | null, createdAt, updatedAt }`. A version is `{ version, sourceSha, actorId, origin, createdAt }`.
+
+| Tool | Takes | Answers |
+|---|---|---|
+| `write_dock_ui` | `{ name, scope: field \| section \| page \| layout, kind: input \| panel, target, source }` | `{ source, version, created }` (`created: false` when the same bytes were already the newest) |
+| `approve_dock_ui` | `{ name, version, userApproved? }` | `{ source }`, status `approved` |
+| `validate_dock_ui` | `{ name, version? }` (default: the newest) | `{ name, receipt }`: `{ ok: true, version, bundleKey, bytes, builtAt }` or `{ ok: false, version, refusals, builtAt }` |
+| `publish_dock_ui` | `{ name, version? }` | `{ ok: true, source, receipt, release: { K, built, cached } }` |
+| `list_dock_ui` | `{ scope?, status? }` | `{ sources, usage: { sources, bytes, limits } }` |
+
+**Who may approve.** A person in the dashboard approves any version (the route needs `content:publish`).
+An agent approves only with the user's yes, sent as `userApproved: true` after they saw the source.
+For a version an agent wrote, the connection must also hold the publish delegation (`content:publish`,
+granted when the user connected the AI client), so an agent never approves its own write on a
+connection that may not publish. A write after the approval drops it: approve the newest version.
+
+### Every refusal, and its fix
+
+| Code | When | Fix |
+|---|---|---|
+| `DOCK_UI_NAME_INVALID` (400) | the name is not lowercase letters, digits and hyphens | rename it |
+| `DOCK_UI_NAME_UNSERVABLE` (400) | it does not start with a letter, or is over 48 characters | rename it |
+| `build.size_exceeded` (413 / 409) | one version over 256 KiB, a 65th source, or the project over 4 MiB (`detail` says which) | split the source, or remove a source you no longer need |
+| `build.import_denied` (422) | an import off the allow-list, a computed `import()`, a `cms:` sibling that is not published, or a source importing itself | import only the allowed packages, as string literals; publish the sibling first |
+| `build.name_conflict` (422) | the site's repo ships a dock UI of the same name | rename one of the two |
+| `build.compile_error` (422 / 409) | the build failed (`detail` names it); "no_site_handle": the project has no site to build for | fix the source; for "no_site_handle", publish the site once, then publish again |
+| `policy.confirmation_required` (403) | `approve_dock_ui` without the user's yes | show the user the source, then approve with `userApproved: true` |
+| `policy.not_approved` (403 / 409) | publishing a version nobody approved; "self_approval": an agent approving its own write without the publish delegation | approve it first; for "self_approval", a person approves it in the dashboard |
+| `DOCK_UI_VERSION_NOT_HEAD` (409) | approving an older version, or a newer one was saved meanwhile | `list_dock_ui`, then approve and publish the newest |
+| `DOCK_UI_NOT_FOUND` / `DOCK_UI_VERSION_NOT_FOUND` (404) | no such name, or no such version | `list_dock_ui` lists them; `write_dock_ui` creates one |
+| `DOCK_UI_REBUILD_FAILED` (502) | the version is published but the UI release failed | nothing to change: the next site release builds it; the stock control shows until then |
+| `DOCK_UI_UNAVAILABLE` (503) | this server has no dock UI storage yet | try again after the server update |
+

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

@@ -30,7 +30,7 @@ Give a fieldset a `kind`:
 |---|---|---|
 | `group` | Fields folded under one header (`collapsed: true` starts it shut) | 12 rows inside one group |
 | `row` | Short fields on one line | at most 3 fields |
-| `tab` | A tab strip | at most 3 tabs, names of 40 characters or fewer, top-level fields only, tabs never nest |
+| `tab` | A tab strip | at most 8 tabs (the ones that do not fit fold into "More"), names of 40 characters or fewer, top-level fields only, tabs never nest |
 
 A group joins a tab with `tab: "<tab id>"`. A fieldset with no `kind` stays flat. Props have no
 fieldsets: the first prop of a group sends `ui.group: { id, label, kind }` and each later one
@@ -49,7 +49,7 @@ from the dock icon list the MCP serves as a resource (`resources/list`); any oth
 
 ## 4. Segmented, dropdown or slider
 
-- `ui.control: "segmented"` on a single-choice select with 2–4 short options: one click replaces
+- `ui.control: "segmented"` on a single-choice select with 2–8 short options: one click replaces
   two. A multi-select or 5+ options is refused; keep the default dropdown there.
 - `"slider"` needs a `number` with numeric `config.min` below `config.max` and at most 1000 steps.
 

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

@@ -203,7 +203,7 @@ and use what it calls things (`plan.cents`, `billingFrequency`, `StatsBand.astro
 | A layout of that kind (a component's `name`) | how THIS layout differs from the kind's others; the kind alone when it has one layout | `Centered`, `Split with media`, `Pricing` | its heading's copy, the page it came from with a number (`Hero 2`) |
 | One placed section's title | nothing you write. The outline shows the section's own heading, as written and read live, with its kind underneath | `Equip Your Projects with ScrewFast` over `Hero` | a `label` you invent, a shortened or reworded heading, the kind said again |
 | A field or prop | what it HOLDS there, one to three words | `Dismiss key`, `Starter plan price`, `Dashboard screenshot`, `Billing frequency` | its own copy, a role with a number (`Text 4`), the section's name alone |
-| Help text | most fields get none. One plain sentence under 90 characters, only for a format or unit, a place the canvas cannot show, a real constraint or a fallback. No semicolons, no dashes, no values from the page | `Leave empty to use the page title.` | the label or the value said again, writing advice, a figure copied from another page |
+| Help text | most fields get none. One plain sentence of at most 160 characters, only for a format or unit, a place the canvas cannot show, a real constraint or a fallback. No semicolons, no dashes, no values from the page | `Leave empty to use the page title.` | the label or the value said again, writing advice, a figure copied from another page |
 
 **Advice is not work left**, except the names. `gate.naming` is part of the job: rename every
 row before you report, as above. `receipt.gate.advice`, `gate.families` and `gate.kit`

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

@@ -110,7 +110,7 @@ The pipeline with the code that enforces each hop.
 
 | # | Hop | Code |
 |---|---|---|
-| 1 | Define: `create_form` / `update_form`, or the dashboard. Postgres `forms` row, `status` defaults to `draft` | `packages/db/src/schema/forms.ts:35` |
+| 1 | Define: `create_form` / `update_form`, or the dashboard. Postgres `forms` row, `status` defaults to `published` (a `draft` when the creator may not publish) | `packages/db/src/schema/forms.ts:35` |
 | 2 | Publish: `publish_form`, or the dashboard Forms tab. Both need publish permission | `src/routes/management/forms.ts:276`, `src/routes/admin/forms.ts:529`, `:530` |
 | 3 | Place: a `form` block `{ formId }` inside a section | `packages/types/src/block.ts:253`, `:257` |
 | 4 | Render: hosted renderer, Next `BcmsForm`, or Astro `BcmsForm.astro` | `packages/next/src/form.tsx:74` |

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

@@ -13,6 +13,17 @@ any vendor with a public HTTPS API and a key works the same way.
 Everything here can also be done by a person in the dashboard (Site settings → Integrations), with the
 same records. What you declare, they see and can edit.
 
+## Contents
+
+- [1. The order of work](#1-the-order-of-work) · [2. Declaring one](#2-declaring-one)
+- [3. Approval](#3-approval) · [4. Calling the vendor](#4-calling-the-vendor)
+- [5. Token exchanges](#5-token-exchanges) · [6. Syncing a list into a collection](#6-syncing-a-list-into-a-collection)
+- [7. A custom panel (always build one)](#7-a-custom-panel-always-build-one) · [8. Recipes](#8-recipes)
+- [9. Webhooks: the vendor tells the site something changed](#9-webhooks-the-vendor-tells-the-site-something-changed) · [10. Functions: your own code, never your secrets](#10-functions-your-own-code-never-your-secrets)
+- [11. Site endpoints: live reads for visitors, no key in the page](#11-site-endpoints-live-reads-for-visitors-no-key-in-the-page) · [12. Live references: point at a vendor item without copying it](#12-live-references-point-at-a-vendor-item-without-copying-it)
+- [13. Sign in with OAuth (the customer's own OAuth app)](#13-sign-in-with-oauth-the-customers-own-oauth-app) · [14. Templates, the call log, alerts](#14-templates-the-call-log-alerts)
+- [15. Two-way sync: BetterCMS edits go back to the vendor](#15-two-way-sync-bettercms-edits-go-back-to-the-vendor)
+
 ## 1. The order of work
 
 1. **Model where the data lands.** A collection per vendor list (Jobs, Products), with fields for
@@ -52,7 +63,7 @@ create_integration {
 ## 3. Approval
 
 Until an admin approves the integration, every vendor call and sync is refused (409
-`integration_not_approved`). You cannot approve it: no tool and no header does. The create and
+"integration_not_approved"). You cannot approve it: no tool and no header does. The create and
 update answers carry `approval.changes` (in plain words: which hosts it will call, which env vars
 it will read, where it sends them) and `approval.approveUrl`. Give the user both, and say why the
 integration needs each host and secret. They (or an admin) press Approve on that page.
@@ -262,7 +273,7 @@ update_integration { functions: [{ name: "to-hubspot", triggers: ["form:<formId>
 - Return `{ upsert: [{ sync, externalKey, data, slug? }] }` to write entries into a sync's
   collection (drafts, like a sync). `run_integration_function { waitSeconds: 20 }` answers with the
   output, the captured `console` lines and any error; runs are in `get_integration.functionRuns`.
-- If the server answers `functions_not_enabled`, functions are not available yet on this
+- If the server answers "functions_not_enabled", functions are not available yet on this
   BetterCMS server: use a sync or an endpoint instead.
 
 ## 11. Site endpoints: live reads for visitors, no key in the page