@bettercms-ai/mcp 0.66.3 → 0.66.4

package/dist/skills/bettercms/SKILL.md

@@ -84,7 +84,8 @@ These hold on every task. The reference in brackets has the detail and the codes
 13. **A build makes a site live, not editable.** It brings in SEO and meta, media, the brand and
     the models `bcms-content.json` declares. Pages, collections, forms, bindings and components
     are `editor_setup`'s: run it after an import or a rebuild (`get_deploy_status` `editorSetup`
-    `never` or `stale`). [getting-started.md]
+    `never` or `stale`). It also fills missing meta, merges identical components and adopts
+    declared bindings when proven; do only what get_next_steps still lists. [getting-started.md]
 
 ## What you do, and what only the owner does
 
@@ -118,6 +119,7 @@ resources: `bettercms://skill/bettercms` for this file, and each reference under
 | Move content out of another CMS (Cosmic, Contentful, Sanity, Strapi, Prismic, WordPress…) | [external-content.md](references/external-content.md) | a CMS SDK in package.json; `envWarning` on import; pages that render empty without a third-party key | Contentful, Sanity, Strapi, envWarning, missing key, empty pages |
 | Pages vs collections, folders, fields, schema changes | [content-modeling.md](references/content-modeling.md) | modelling a route family; a model write returns 409 | schema, model, collection, field, folder, rename, remove field |
 | Dock layout: groups, rows, tabs, icons, item names, showIf order | [editor-chrome.md](references/editor-chrome.md) | `get_next_steps` lists a `dock-*` rule; the `field-ui` prompt | dock, fieldset, tab, group, itemLabel, showIf, field-ui |
+| A custom input for one field in the dock: when, the user's approval, the contract | [dock-input.md](references/dock-input.md) | `get_next_steps` lists `dock-input-candidate`; a 409 `input_needs_confirmation` | custom input, ui.input, dock input, confirmed, swatch |
 | What the server does and does not check on a write | [write-limits.md](references/write-limits.md) | before relying on a limit; reading a refused write | validation, maxLength, unique, 400, refused write |
 | Plan a site by business type | [site-blueprints.md](references/site-blueprints.md) | portfolio, agency, corporate, SaaS/AI or ecommerce IA | new site, IA, sitemap plan, portfolio, SaaS, ecommerce |
 | Components, props, variants, component publish codes | [components.md](references/components.md) | creating, swapping, publishing or validating a component | component, prop, variant, sectionType, publish component |

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

@@ -0,0 +1,115 @@
+---
+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."
+---
+
+# Custom dock inputs
+
+**Outcome.** A field whose choice the stock dock cannot show (a colour, a preset scale, one look
+set by several props) gets a small input the user approved, and every other field keeps the stock
+control. Nothing an author or a visitor sees can break because of it.
+
+## 1. The restraint ladder
+
+Industry practice: a custom input is the last resort. Climb in this order and stop at the first
+rung that works.
+
+1. **The stock control.** The field type already draws one: text, number, select, boolean, image.
+2. **A composition of ui keys.** `ui.control` (`segmented` for a short single choice), `ui.preview`
+   and `ui.layout` for list items, `ui.group` for props, model `fieldsets` for groups, rows and
+   tabs. See editor-chrome.md.
+3. **A custom input.** Only when rungs 1 and 2 cannot show the choice, and only with the user's yes.
+
+A custom input never adds data. It draws fields that already exist in the schema.
+
+## 2. Suggest, then the user approves
+
+`get_next_steps` lists `dock-input-candidate` when a field or prop looks like it needs one. Each
+row has the field `key`, a `reason` and, for a look set by several props, the sibling keys it would
+`writes`. The rule is a candidate list, never a defect.
+
+1. Check rungs 1 and 2 for each row. Drop rows they cover.
+2. Ask the user, in one message per field: name the field, the input you would write and the
+   reason the stock control cannot do it. Wait for an explicit yes.
+3. On yes: write the input file (section 5), then set `ui.input` with `confirmed: true`. These
+   merge into the stored `ui`:
+   `update_content_model { modelId | pageId, fieldUi: { "<path>": { input: { name, writes } } }, ifMatch, confirmed: true }`,
+   `update_component { componentId, propUi: { "<key>": { input: { name, writes } } }, ifMatch, confirmed: true }`.
+   `update_field`'s `ui` REPLACES the field's whole `ui`: send every key you read with it.
+4. On no: leave it. Nothing is broken.
+
+A write through the agent tools that sets or changes `ui.input` without `confirmed: true` is
+refused 409 `input_needs_confirmation`, naming each path. `confirmed: true` is true only after the
+user approved that input; never send it to get past the refusal. Removing `ui.input` (send
+`input: null`) needs no approval. The create tools carry no approval: create the field without
+`ui.input`, then add it with `update_field` or `update_component`. A person saving in the
+dashboard is the approver and is never asked.
+
+## 3. The contract
+
+The input is a React component that receives `DockInputProps` from `@bettercms-ai/dock-input`:
+
+| Prop | What it is |
+|---|---|
+| `value` | this field's current value |
+| `field` | `{ key, label, type, required, readOnly, writes, config? }`: the stored options and limits |
+| `document` | a read-only snapshot of the whole document's values, by field key |
+| `readOnly` | true when the author may not edit; draw the value, accept nothing |
+| `theme` | `"light"` or `"dark"`, for the kit theme |
+| `onChange(value)` | set this field |
+| `writeFields(patches)` | set this field and siblings listed in `field.writes`, together |
+
+`writeFields` takes `[{ field, value }]`, applies all of them or none to the DRAFT, as one undo
+step, and resolves `{ ok, reason? }`. Show the `reason` when `ok` is false.
+
+Build the UI from `@bettercms-ai/kit` so it matches the dock in both themes. The input never sees a
+token and makes no network call for content: everything it needs arrives as props.
+
+## 4. Writes discipline
+
+`ui.input.writes` lists EVERY sibling field key the input writes, and nothing else. The dock
+refuses a patch to a key outside it, and checks each value against that field's own schema. A
+button-look input over `buttonVariant` set on `buttonVariant` declares
+`writes: ["buttonSize", "buttonColor"]`. An input that only edits its own field omits `writes`.
+At most 16 keys, each an existing sibling.
+
+## 5. File layout
+
+One file per input, in the site's repository:
+
+```
+bettercms/inputs/<name>.tsx
+```
+
+- `<name>` is the `ui.input.name`: lowercase letters, digits and dashes, 1 to 48 characters,
+  starting with a letter (`button-look`, `brand-swatch`).
+- The default export is the component. The file also calls `mountDockInput(Component)`, which
+  speaks the protocol (section 6) so the component only deals with props.
+- Keep it small and self-contained: kit components and the field's own data, no app imports.
+
+## 6. Protocol summary
+
+`bcms-input/1`, over `window.postMessage` between the dock and a sandboxed frame served from the
+project's own inputs origin, never the dashboard's. `mountDockInput` handles all of it.
+
+- Dock to input: `init` (field, value, document, theme), `value` (after a commit), `result`
+  (the verdict on a `change`), `readOnly`.
+- Input to dock: `ready`, `change` (an id and its patches), `height`, `focus`, `blur`, `error`.
+- Every message carries the session nonce from `init`; the dock drops anything else.
+- Limits: a patch is at most 64 KB of JSON, at most 10 patches per second, and `ready` must arrive
+  within 3 seconds. Larger or faster messages are refused, never truncated.
+
+## 7. Build, serve and scope
+
+- v1 is managed sites only (BetterCMS hosting). On a headless or hybrid site, do not suggest one.
+- Once custom inputs are enabled for the project, the inputs are built with the site and served
+  on its inputs origin automatically. Push the file, wait for the build, then open the field in the
+  dock to check it.
+- Name only inputs that exist in `bettercms/inputs/`. An unknown name is not an error, it falls back.
+
+## 8. The fallback guarantee
+
+The stock control comes back whenever the input cannot run: an unknown name, inputs disabled for
+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.

package/dist/skills/bettercms/references/getting-started.md

@@ -68,7 +68,9 @@ and `get_componentize_plan` proposes nothing more.
 0. A build brings in only SEO and meta, media, the brand and the models `bcms-content.json`
    declares. Pages, collections, forms, bindings and components come from `editor_setup`: run it
    and poll `editor_setup { check: true }` until `ready` before anything below. Run it again
-   whenever `get_deploy_status` reports `editorSetup` `stale`.
+   whenever `get_deploy_status` reports `editorSetup` `stale`. It also fills missing meta from the
+   page copy, merges identical components and switches to declared bindings when the build proves
+   them; the receipt stays yours (it is the codemod's account of your repo).
 1. Explore the repo (the "Read when" column of SKILL.md's reference table names the signals) and
    read `get_site_composition`.
 2. If `list_env_vars` reports `missing` variables, run `npx @bettercms-ai/cli@latest env push`

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

@@ -31,10 +31,12 @@ Two things are called a "language" here, and they are separate:
 | Layout locale variants | A Global Layout Section can have a variant per locale (`navigation--fr`). A page renders the variant whose locale is its route's first segment, else the base |
 | `locale-unvarianted` | A `get_binding_report` unmatched reason: the route resolved in a locale, the Section has no variant for it, and the base still renders there. Named, never written |
 
-Import derives deeper locale routes (`/fr/about`, `/fr/blog/post-1`) as pages in a URL folder
-(`fr`), each recording the language its `<html lang>` declares, and the Content sidebar files them
-under Pages › <language>. A locale prefix is never a collection: `/fr/blog/*` are pages, not
-entries of the `blog` collection. An edit to `/about` never reaches `/fr/about`; edit each page.
+Import derives deeper locale routes (`/fr/about`) as pages in a URL folder (`fr`), each recording
+the language its `<html lang>` declares, and the Content sidebar files them under Pages › <language>.
+A locale prefix is never a collection, but a collection's localized posts (`/fr/blog/post-1`, its
+`<html lang>` agreeing) are entries of that collection with `locale` set, `translationOf` the post
+their hreflang alternate (else their slug) names, slug `<slug>-<locale>`; the project's locales gain
+each language found. An edit to `/about` never reaches `/fr/about`; edit each page or entry.
 
 ## 2. Never model
 

package/package.json

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