@bettercms-ai/mcp 0.86.0 → 0.87.0

package/dist/kit-catalog.json

@@ -148,7 +148,8 @@
    "lead",
    "band",
    "family",
-   "shape"
+   "shape",
+   "staleRule"
   ]
  },
  "categories": [

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

@@ -15,10 +15,12 @@ Industry practice: a custom input is the last resort. Climb in this order and st
 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`
+2. **The stock form, restructured.** Order the props, drop the tab strip, fold Design under the
+   content, regroup: one `update_component` `dock` write (editor-chrome.md §10).
+3. **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.
+4. **A custom input.** Only when rungs 1 to 3 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.
 
@@ -28,7 +30,7 @@ A custom input never adds data. It draws fields that already exist in the schema
 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.
+1. Check rungs 1 to 3 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
@@ -137,7 +139,9 @@ restraint ladder (section 1) and the user's yes (section 2) still come first.
 | 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 |
+| — | `list_dock_ui { scope?, status? }` | every source, its status, `notShown` and the project's usage |
+| — | `publish_dock_ui { name, action: "unpublish" }` | off the dock; the release is rebuilt without it |
+| — | `publish_dock_ui { name, action: "delete" }` | removes an UNPUBLISHED source and every version |
 
 - `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).
@@ -154,6 +158,15 @@ restraint ladder (section 1) and the user's yes (section 2) still come first.
   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).
+- The dock mounts an `input` at the `field` scope and a `panel` at `section`, `page` or `layout`. Any
+  other pair refuses `protocol.unsupported` at write and validate.
+- **Published is not shown.** approve, validate and publish answer `dockInputs: { enabled, platform }`,
+  and `notShown: { reason, fix }` when the dock will not draw it: "flag_off" (the project's Custom inputs
+  switch is off), "platform_off" (this server has it off), "switched_off" (an admin turned that input
+  off). Publish still succeeds. Tell the user the `fix`: a project admin turns on Custom inputs in
+  Project settings › General › Visual editor. Never flip it yourself; no tool can.
+- Clean up test UI: unpublish (refused `DOCK_UI_IN_USE` while a published sibling imports it), then
+  delete (refused `DOCK_UI_PUBLISHED` while published). Both are recorded in the activity log.
 
 One minimal example per scope. The `target` says what the UI is for.
 
@@ -183,10 +196,12 @@ buildReceipt | null, createdAt, updatedAt }`. A version is `{ version, sourceSha
 | 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 } }` |
+| `approve_dock_ui` | `{ name, version, userApproved? }` | `{ source, dockInputs, notShown? }`, status `approved` |
+| `validate_dock_ui` | `{ name, version? }` (default: the newest) | `{ name, receipt, dockInputs, notShown? }`: 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 }, dockInputs, notShown? }` |
+| `publish_dock_ui` | `{ name, action: "unpublish" }` | `{ source, wasPublished, release: { K, built, cached } \| null }` |
+| `publish_dock_ui` | `{ name, action: "delete" }` | `{ deleted, versions }` |
+| `list_dock_ui` | `{ scope?, status? }` | `{ sources, usage: { sources, bytes, limits }, dockInputs }`; each source carries `notShown?` |
 
 **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.
@@ -209,5 +224,8 @@ connection that may not publish. A write after the approval drops it: approve th
 | `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 |
+| `protocol.unsupported` (400 / 422) | a kind and scope the dock never mounts (an input outside `field`, a panel at `field`) | write it with a scope the dock mounts |
+| `DOCK_UI_IN_USE` (409) | unpublishing a source a published sibling imports | unpublish the sibling first |
+| `DOCK_UI_PUBLISHED` (409) | deleting a published source | unpublish it first |
 | `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

@@ -86,6 +86,95 @@ A Global field with `overridable: false` and a `lockReason` is not offered on a
 of it answers 403 **LAYOUT_FIELD_NOT_OVERRIDABLE** with the reason. A page value written earlier is
 kept but the Global value renders; `get_layout` scope page lists it under `shadowed`.
 
+## 9. Names and help on an imported site
+
+An import names the dock for you. A setup run or a release runs the naming pass whenever the
+project's `naming` receipt is behind the current rules version (`naming-2`); it does not mark setup
+stale, and a second run writes nothing. On a project whose setup is already `ready`, run it with
+`editor_setup` `force: true`. The pass runs in the background, one at a time per server, so poll
+`editor_setup` `check: true`: `setup.namingRun` is the latest run {runId, state, clean, ms, steps,
+counts, errors}, its state queued → running → done or failed (skipped when the rules were already
+current). Only a clean run stamps `setup.naming` {version, at, runId, counts, refusals}. A check
+never starts the pass.
+
+What the pass changes on its own, only where the platform wrote the old value:
+- **Labels.** A label that is copied text, alt text or an artifact name becomes the bare V2 label
+  of its role: "Heading", "Eyebrow", "Intro", "Body", "Image", "Primary button", "Number",
+  "Rating", "Quote". A repeat inside one section or component gets " 2" ("Image 2"). A whole-button
+  prop or field ("Hero Primary Cta") becomes "Primary button" or "Secondary button".
+- **Lists.** A list takes a plural noun ("Questions", "Features", "Links", "Logos"), its row
+  sub-fields their roles ("Question" / "Answer", "Title" / "Description" / "Icon", "Label" /
+  "Links to"), and, where its `ui` names none, `ui.itemLabel` ("Question") and `ui.preview.title`.
+- **Help.** A field or prop with no real help gets the kit's help text for its role.
+- **Section kind and name.** A machine-made kind (a heading's first word, like "Equip") becomes the
+  section family ("Hero", "Stats", "Testimonials"…), and the name a phrase from its heading. A
+  placement titled with that first word, or untitled, takes its component's name; a person's title
+  stays.
+- **Type.** "7k+" becomes a number with suffix "k+"; "4.8 / 5" a number with the rating control.
+  A retyped number (not a rating) also carries `config.unit`, its suffix or prefix ("k+", "$"),
+  which the dock shows beside the input.
+- **Stale.** Decorative icons and per-page copies of Layout chrome are made stale, so they leave
+  the "couldn't connect" list.
+
+It never touches keys, ids, slugs or values (except an allowed retype), nor a label, help or `ui`
+a person or agent wrote, nor a repository-managed component. Don't redo its work by hand: a label
+you write is yours and the pass leaves it alone from then on.
+
+Each refusal keeps the field as it is and names why:
+
+| Reason | Means | Do |
+|---|---|---|
+| **person-named** | A person set this label | Leave it; rename only when the user asks |
+| **person-helped** | A person or agent owns this help | Leave it |
+| **retype-code-reads-value** | The site's code reads this value, so a number would change the live text (helper older than v24, or the build declares its own bindings) | Keep the text type. After the site runs `@bettercms-ai/convert` helper v24 or newer and rebuilds, the next run retypes it |
+| **retype-not-lossless** | The text does not round-trip exactly as a number ("about 7k") | Nothing: text is the right type |
+| **regroup-would-rekey** | Numbered siblings ("Avatar 1–4") would become one list, which changes keys | They stay separate fields. A list needs a re-import, with the user's approval |
+| **kit-low-confidence** | No kit entry matched clearly enough to borrow its labels and controls | Role labels only; refine with `update_field` if the user wants |
+| **cta-modelled-twice** | A call to action exists as loose fields and as a button field, and the template declares neither | It stays in "couldn't connect". Fix by re-converting the source, or drop one copy with the user's approval |
+| **decorative** | A decorative icon (an SVG data URL, hidden or untitled) | Made stale. Never bind or label it |
+| **layout-owned** | The value belongs to the Global Layout | Counted once on the Layout; edit it with `update_layout` |
+| **repository-managed** | The component belongs to the repository, whose next push rewrites it whole | Rename it in the source, not here |
+| **not-machine-named** | A person or agent wrote the component's name and family | Leave them |
+| **shown-again** | A person set `stale: false` on the field | Leave it shown; the pass never hides it again |
+
+## 10. Restructure a section
+
+The stock form, rearranged, comes before any custom input (dock-input.md §1). The scope is the
+component: every placement shows the same form. Order, tabs and the Design fold apply at once, show
+the "Layout by agent" badge, and the user can revert them in one click. Tabs appear only when
+declared (`ui.tab`, a fieldset of kind `tab`, the kit's groups); there are no automatic
+Content | Media tabs.
+
+Decide the shape from the user's words, read with `get_component` (§1), then send ONE
+`update_component` with `dock`:
+
+| The user wants | Send |
+|---|---|
+| One form, text first, then media | `dock: { propOrder: ["heading", "intro", "primaryButton", "image"], tabs: "none" }` |
+| Design controls kept apart (or says nothing) | `design: "tab"`: today's Content \| Design |
+| Design under the content, one scroll | `design: "fold"`: a Design group below the content (only on a designable section) |
+| Related props together | `propGroup`, as in §2 |
+| The old form back | `tabs: null`, `design: null`, and the old `propOrder` |
+
+- `propOrder` names every top-level prop key exactly once. A missing, unknown or repeated key is
+  400 `prop_order_invalid`, which names the key.
+- `tabs` takes "none" or null (else `dock_tabs_invalid`); `design` takes "tab", "fold" or null
+  (else `dock_design_invalid`).
+- `tabs: "none"` keeps any stored `ui.tab`, so null brings the tabs back. A prop added later still
+  draws.
+- A person's own arrangement answers 409 **ui_human_owned**: send `override: true` only when the
+  user asked you to replace it.
+
+**Hiding takes the user's yes.** Hiding a field (`ui.hidden`), moving it into `advanced` or a
+collapsed group, or demoting it from required to optional changes what an editor can find:
+1. Ask first, naming each field and why ("Hide 'Badge'? This page never shows it").
+2. Only after a yes, send the write with `confirmed: true`. Without it the answer is 409
+   `hide_needs_confirmation`, with the `paths` and each `change`.
+3. A required field is never hidden: 409 **required-field-hidden**, hint "demote it first
+   (required:false, confirmed)". Ask the user to make it optional. On a yes, send `required: false`
+   with `confirmed: true` (`update_field` for a field, the prop in `props` for a component), then
+   hide it in a second confirmed write. Never demote just to get past the refusal.
+
 ## Acceptance
 
 Read back with `get_content_model`, `get_page` or `get_component`. Done means `get_next_steps`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/mcp",
-  "version": "0.86.0",
+  "version": "0.87.0",
   "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.37.0",
+    "@bettercms-ai/sdk": "^1.38.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.3.6"
   },