@bettercms-ai/mcp 0.76.4 → 0.76.6

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

@@ -297,3 +297,43 @@ fields, submitUrl). After the binding pass, run the codemod's forms mode (`npx
 @bettercms-ai/convert --forms`, with the brief and a receipt file) to wire them into the
 repository's own `<form>` elements. Read `forms.pending`, and publish every form `forms.notes` names in the Forms tab: a draft
 form rejects every submission with a 403.
+
+## Editor setup, proposals and binding decisions
+
+`editor_setup` derives what a build no longer imports: a build brings in SEO/meta, media, brand and
+the models `bcms-content.json` declares; editor setup adds pages, collections, forms, bindings,
+button and section components (when the authoring preference is components), Component Groups and
+the Content sidebar. `get_deploy_status` `editorSetup` reports its state.
+
+The complete brief's `proposals` (page 1, at most 50; `proposalsMore` when there are more) list
+what the last convert found and no field owns: `{ id, kind, target, text, suggested?, evidence? }`.
+`id` is `pr_` and 16 hex and survives re-runs; `target` is a `file:line:col` locator only. Kinds:
+`unaddressable` and `code-candidate` (copy no field owns), `inert` (declared, nothing reads it),
+`mismatch` (declares one path, reads another), `flatten` (two leaves in one element).
+
+Answer them with `editor_setup { declare: [item, …] }` (at most 100 items, one result each;
+`check: true` with `declare` is a dry run that stores nothing):
+
+- `{ op: "accept", ids }` takes each proposal's `suggested` op. A proposal with none refuses.
+- `{ op: "bind", id, path, owner? }` binds the copy to an existing field; `owner` is a route or
+  `layout`. The next convert writes it into the source (a mismatch's declaration is rewritten; an
+  attribute or an expression is reported `manual` in `receipt.decisionsApplied`). A `bind` waits as
+  `decision-pending` until a build proves the new read; one still pending after the next release
+  blocks the gate. A declared element is corrected through its `mismatch` proposal id.
+- `{ op: "code", id, why, system? }` keeps it in code. `why` is one of `runtime`, `external`,
+  `derived`, `stylesheet`, `decorative`, `embed`, `legal`, and the system checks its evidence;
+  without it the item refuses `evidence-missing` (bind it, pick the reason that fits, or a person
+  marks it in Overview). The next convert writes `data-bcms-code-owned="text why:<id>"`; the
+  `code` counts once a build carries it. Each convert re-checks the
+  facts: one whose reason no longer holds becomes `evidence-lost`, blocks the gate, and returns to
+  the proposals to decide again. Facts are same-file only: a value from another file needs a person.
+- `{ op: "reject", ids }` drops the suggestion; the copy stays unaddressable. A person's reject of
+  an AI `code` is its Undo: the next convert removes the token.
+- `{ op: "clear", decisionId }` undoes a decision.
+
+A person's decision beats yours: add `force: true` and a `reason` (shown to them) only when they
+asked for it. Refusals per item: `target-unknown`, `path-not-in-schema`, `owner-mismatch`,
+`locked-by-person`, `slot-mismatch`, `evidence-missing`, `declaration-conflict`, `invalid-item`.
+Until a convert that emits proposals has submitted its receipt, every id refuses `target-unknown`.
+`get_next_steps` `receipt.decisions` counts `stored`, `materialized`, `proven`, `pending` (open
+proposals) and `lost`; stop when `pending` is 0.

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

@@ -81,7 +81,7 @@ Never let a component contain itself, directly or through a child.
 
 ## 3. Names and groups
 
-The import's kit entry (`kit: suggested <id> <score>`, the `hint` of its row in `receipt.gate.kit`) is only a suggestion: nothing is recorded, and nothing waits on it. The props already carry the ui that suggestion gives. For each component, read `bettercms://kit/entry/{id}`, check its `htmlSignals` against the section's own HTML and its pitfalls against the props, then confirm it or pick the right one from its category in `bettercms://kit` and name it with `update_component { kitEntry }`. Setting or changing `kitEntry` puts that entry's ui over the derived ui: where the entry specifies a tab, group, control or preview key for a prop, the entry wins; what it says nothing about stays as derived; ui you or a person set is kept. The `no-kit-match` exemption needs a note.
+The import's kit entry (`kit: suggested <id> <score>`, the `hint` of its row in `receipt.gate.kit`) is only a suggestion: nothing is recorded, and nothing waits on it. The props already carry the ui that suggestion gives. For each component, read `bettercms://kit/entry/{id}`, check its `htmlSignals` against the section's own HTML and its pitfalls against the props, then confirm it or pick the right one from its category in `bettercms://kit` and name it with `update_component { kitEntry }`. Setting or changing `kitEntry` puts that entry's ui over the derived ui: where the entry specifies a tab, group, control or preview key for a prop, the entry wins; what it says nothing about stays as derived; ui you or a person set is kept. It also carries the entry's rules (showIf, limits, patterns, options, required) onto props that have none of their own. A component whose props still lack some gets a `gate.kit` row with `drift` listing each one as `path.key=value`: add them with `update_component { props }`, or record `kit-drift-accepted` with a note. The `no-kit-match` exemption needs a note.
 
 Name a family by what it is (`Hero`, `CTA`, `Testimonials`) and each variant by how it looks
 (`Hero / Split`, `CTA / Centered`). Never put a page name in a reusable definition; which pages

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

@@ -74,7 +74,7 @@ line), which is what a script waiting on the setup reads.
 | `collections` | sibling routes that are one family (three under one parent, or two under `tags`, `category`, `author`) are a collection; reported on the family's listing route, built or not | `blocking.rows` |
 | `buttons` | every button field is one of the site's live Button looks, the Button family is the looks setup measured on this build (the same looks, not the same count), and no look is named by a number or a build's class | `blocking.rows`, `route: null` |
 | `components` | the authoring question is answered, and no section is left that a componentize run would place. A heading or paragraph that stands outside any section is a field of its page, not a section: advice (`receipt.gate.advice`) | `blocking.rows`, `route: null` |
-| `forms` | every form of the customer's has an address to notify; a form setup ignored (sign-in, add to basket) is not counted | `blocking.rows`, `route: null` |
+| `forms` | every form of the customer's reaches somebody: its own address, else the project's default, else the workspace's owners, the order a submission is sent in; a form setup ignored (sign-in, add to basket) is not counted | `blocking.rows`, `route: null` |
 | `dock` | no component is left with props the server's own ui derivation would still dress: one it has not reached has no prop carrying V2 `ui`, or a list prop (`table`, `array`, `multi-reference`) with no row title (`ui.preview.title` or `ui.itemLabel`). The import derives each prop's ui when it makes a component, from its closest `bettercms://kit` entry or the generic rules, so a fresh import has no such row; a component whose props it leaves to the default controls (two short texts) is done. Button looks are not counted. Which kit entry a component IS is not part of this check: it is advice, `receipt.gate.kit` (below) | `blocking.rows`, `route: null`, the component and its props in `detail` |
 
 `pages` counts routes built, created and published. `coverage` sums `editable` of `total` across
@@ -112,7 +112,7 @@ The other rows name their fix the same way:
 | `model-collection` | not a row any more. Setup derives a collection wherever a family's pages share one template, with its fields, its entries and their bodies. A family it left as pages is listed as advice in `receipt.gate.families`: every route in it is an editable page. **Never `create_content_model` for it on an imported site.** One hand-written model reads the whole project as hand-authored, and the import then registers no further page, derives no collection and adds no field, which is where "the model holds only title and description" comes from. Mention the family to the owner as something a collection could hold later, and go on |
 | `derive-buttons` | `editor_setup { force: true }` mints a Button for each look the build draws, retires one it no longer draws and maps each button to its look; rename a look with `update_component` ([components.md](components.md)) |
 | `componentize` | `set_authoring_preference` when nobody answered, then `get_componentize_plan` and `componentize_sections` ([componentize.md](componentize.md)) |
-| `set-form-recipient` | `update_form` with `notifyEmails` set to the address the owner gave when setup started (it is in your first prompt); `update_form { ignored: true }` when it is not one of their forms. Only a form the built site posts to BetterCMS is listed, and the release publishes it once it is wired. Never ask for an address at the end of a run |
+| `set-form-recipient` | `update_form` with `notifyEmails` set to the address the owner gave when setup started (it is in your first prompt); `update_form { ignored: true }` when it is not one of their forms. Only a form the built site posts to BetterCMS is listed, and only when a submission would reach nobody at all (no address on the form, none on the project, no owner on the workspace); the release publishes it once it is wired. Never ask for an address at the end of a run |
 | `set-dock-ui` | the last step of the repair order below: `get_component`, then `update_component` with `propUi` and `propTab` for the props the row names ([editor-chrome.md](editor-chrome.md)) |
 
 A row nothing measured reads `unmeasured: true` with `run-setup`, and `gate.unmeasured` lists the

package/dist/skills/bettercms/references/media-and-brand.md

@@ -125,7 +125,7 @@ value to its asset. Check it, never redo it: the binding report's `elementCovera
 |---|---|---|
 | `IMG_DATA_URI`, `IMG_NO_SOURCE` | An `<img>` inlined as `data:`, or filled in by a script | Ship it as a file with a real `src` |
 | `BG_PSEUDO_ELEMENT` | A background on `::before` / `::after` | Move it onto the element, or render an `<img>` |
-| `BG_ON_TEXT` | A background on an element that is itself a text field | Wrap the text, so the box and the words are two elements |
+| `BG_ON_TEXT` | A background on an element that is itself a text field, or on a section whose copy sits directly in it. A section that keeps its copy in one wrapper is never listed: the picture is the section's field and the copy the wrapper's | Wrap the text, so the box and the words are two elements |
 | `SVG_TOO_LARGE` | An inline `<svg>` past 64 KB | Ship it as an `.svg` file in an `<img>` |
 | `SVG_SPRITE` | A `<use>` naming a symbol the page does not hold, or a sprite FILE the build does not ship (another host's, a relative path) | Inline the symbol in the page, serve the sprite from the site root, or ship the icon as its own `<svg>` |
 | `IMAGE_NOT_ASSET` | A header or footer picture the Media library holds no asset for | Nothing lost: the rest of the region is the Layout's and this picture stays a field of each page. Setup tries it again on the next build |

package/package.json

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