@bettercms-ai/mcp 0.76.5 → 0.77.0

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

@@ -297,3 +297,70 @@ 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.
+
+### Archive (ZIP) sites
+
+A project with no connected repository and no receipt carrying proposals is an ARCHIVE site: no
+codemod runs, so each release scan mints the proposals itself. `target` is then
+`template|owner|textHash` (owner `page`, `layout` or `entry:<collection>`; Layout copy has template
+`*`, an entry route its collection's `/blog/*`), and translations of a page share one template.
+Decisions are not written into source: every release stamps them into the built HTML wherever
+their anchors (structure, text, nearest declared field) agree 2 of 3, else the row is `lost`
+(`anchor-lost`). A `bind` stamps only when the element's text equals the field's stored value; an
+uploaded copy change loses it (`anchor-text-changed`) and its copy is proposed again. An AI `code`
+for `runtime`, `external`, `derived` or `stylesheet` refuses `evidence-missing` here (there is no
+source to check); `decorative`, `embed` and `legal` are checked on the page, and a person may mark
+any reason. Each such decision lives in BetterCMS, not in the site's code: recommend connecting a
+repository.
+
+Archive sites also take `{ op: "rule", template, match, then }`, one row for every element it
+matches on every route of `template`:
+- `template`: `/`-segments literal or `*`, a trailing `/**`, or `*` alone (every route). No regex.
+- `match`: at least one of `struct` (a proposal's structure anchor), `cls` (one class token),
+  `text` (exact copy); `owner` (`page`, `layout`, `entry`) narrows.
+- `then`: `{ op: "code", why }` or `{ op: "bind", path }`. A bind rule names a `layout` or `entry`
+  owner, and matching more than one element on a route is `ambiguous` there.
+A person beats an AI, then a per-id decision beats a rule; two rules saying different things about
+one element are `declaration-conflict`. On a git site a `rule` refuses `invalid-item`. A lane change
+(a repository connected, or a convert's receipt arriving) loses the other lane's decisions
+(`lane-changed`): decide again on the new proposals.

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/dock-input.md

@@ -35,7 +35,7 @@ row has the field `key`, a `reason` and, for a look set by several props, the si
    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.
+   `update_field`'s `ui` MERGES per key into the stored `ui`, as `fieldUi` does: send `null` for a key to clear 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

package/dist/skills/bettercms/references/kit-catalog.md

@@ -114,7 +114,7 @@ Tags: deep-nesting, slots, global-synced, conditional, references, variants, com
 - If two menu items share the same panel content, that is still two panels in content; don't invent a shared-panel global for it.
 - Hover-only panels fail keyboard users — the converter should default `openOn` to click when the source has no aria-expanded handling.
 
-Not carried by a stored component: ai, category, kind:global, shopify reference, variants.
+Not carried by a stored component: ai, category, kind:global, shopify reference, slot allow: ctaCard, imageBlock, productCard, videoBlock, variants.
 
 ### Docs sidebar navigation (`nav-docs-sidebar`)
 
@@ -644,7 +644,7 @@ Tags: slots, responsive-layout, conditional, media-heavy, variants. Proves: Slot
 - Phones stack cells; if the source reorders them with CSS `order`, capture it or the story reads out of order.
 - 6-column variants need spans up to 6; validate spans against the variant's column count.
 
-Not carried by a stored component: ai, category, variants.
+Not carried by a stored component: ai, category, slot allow: featureBlock, statBlock, imageBlock, videoBlock, quoteBlock, ctaCard, textBlock, variants.
 
 ### Steps / how it works (`steps-how-it-works`)
 
@@ -922,7 +922,7 @@ Tags: repeater, variants, a11y, validation, conditional, media-heavy. Proves: Gr
 - Alt text like “logo” or empty alt on linked logos fails a11y; the required name fixes it.
 - Conditions on `_variant` work today because the variant is stored on the block value — this is a schema-language gap worth making official.
 
-Not carried by a stored component: category, item openMode, variants.
+Not carried by a stored component: category, item openMode, showIf on _variant, variants.
 
 ### Press mentions (`press-mentions`)
 
@@ -1145,7 +1145,7 @@ Tags: media-heavy, a11y, responsive-layout, variants, conditional. Proves: Art-d
 - Text over a busy photo fails contrast; the overlay help gives a range and the renderer checks contrast.
 - A background-image has no alt — converting to an `<img>` with alt (or decorative) is part of the import.
 
-Not carried by a stored component: ai, category, variants.
+Not carried by a stored component: ai, category, showIf on _variant, variants.
 
 ### Social photo feed (UGC) (`ugc-social-feed`)
 
@@ -2773,7 +2773,7 @@ Tags: deep-nesting, slots, repeater, variants, media-heavy. Proves: Guide › Ta
 - Breadcrumb at 7 drills (Guide / Seasoning / Steps and kit / Steps / Season over fire… / Heat it upside down / Card / Button) must fold into the Pathway chip on a 380px inspector — this entry is the test case.
 - Accordion item cards inside a 1/3 column are cramped; that's a variant decision, not a field.
 
-Not carried by a stored component: ai, category, variants.
+Not carried by a stored component: ai, category, slot allow: layoutColumns, accordionBlock, textBlock, imageBlock, videoBlock, ctaCard, variants.
 
 ### Any-block module list (`polymorphic-modules`)
 
@@ -2928,7 +2928,7 @@ Tags: slots, variants, media-heavy, responsive-layout, commerce. Proves: Slot ce
 - SCHEMA GAP: slotSettings can't be conditional on the child's block type (e.g. padding 'none' only for images) and can't vary per breakpoint.
 - Dense packing changes the visual order but not the DOM order — screen readers follow the DOM.
 
-Not carried by a stored component: ai, category, variants.
+Not carried by a stored component: ai, category, slot allow: imageBlock, productCard, quoteBlock, textBlock, ctaCard, statBlock, videoBlock, featureBlock, variants.
 
 ### References web (`references-web`)
 
@@ -3041,7 +3041,7 @@ Tags: slots, conditional, a11y, form, repeater, references. Proves: Overlays wit
 - Exit-intent doesn't exist on touch devices; the label says '(desktop)' because the schema can't scope a trigger per device.
 - Focus trap, Esc to close and focus return are renderer requirements, not fields — never make them toggles.
 
-Not carried by a stored component: category.
+Not carried by a stored component: category, slot allow: textBlock, imageBlock, videoBlock, ctaCard, quoteBlock, featureBlock.
 
 ### Sticky scroll story (`scrollytelling`)
 
@@ -3172,7 +3172,7 @@ Tags: slots, polymorphic-array, repeater, variants. Proves: Array of tabs, each
 - Slot children are `{ componentId, overrides? }` with no `_variant`: a variant is its own component.
 - Give every block, tab and instance a stable `id`; changing one orphans the edits made against it.
 
-Not carried by a stored component: ai, category, variants.
+Not carried by a stored component: ai, category, slot allow: textBlock, imageBlock, featureBlock, statBlock, quoteBlock, ctaCard, productCard, videoBlock, variants.
 
 ### Pricing (`core-pricing`)
 
@@ -3214,7 +3214,7 @@ Tags: slots, polymorphic-array, variants, responsive-layout, media-heavy. Proves
 - A slot child has no `_variant`: a variant is its own component.
 - slotSettings are leaf fields only; a cell's own copy stays in the cell component's props.
 
-Not carried by a stored component: ai, category, variants.
+Not carried by a stored component: ai, category, slot allow: imageBlock, statBlock, quoteBlock, textBlock, ctaCard, productCard, videoBlock, variants.
 
 ### Journal story (`core-journalStory`)
 

package/package.json

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