@bettercms-ai/mcp 0.38.0 → 0.38.2

package/dist/index.js

@@ -2108,6 +2108,21 @@ var fieldType = z.enum([
 ]);
 var slug = z.string().regex(/^[a-z0-9-]+$/, "lowercase letters, numbers, and hyphens only");
 var fieldKey = z.string().regex(/^[a-zA-Z0-9_]+$/, "letters, numbers, and underscores only");
+var uiObject = z.object({
+  collapsed: z.boolean().optional().describe("start this panel collapsed. Use it for long optional sections."),
+  preview: z.object({
+    title: z.string().min(1).optional().describe("CHILD KEY whose value titles a collapsed row"),
+    media: z.string().min(1).optional().describe("CHILD KEY whose value is the row's thumbnail (image/file/url all work)")
+  }).optional().describe(
+    "how ONE ITEM summarises itself when collapsed. Both slots name a CHILD KEY of THIS field/prop \u2014 not a value, not a dotted path. Without it a repeater of testimonials reads 'Item 1, Item 2, Item 3'; with {title:'author', media:'avatar'} it reads the names with their faces."
+  ),
+  layout: z.enum(["list", "grid"]).optional().describe(
+    "how the ITEMS are arranged. Omit (\u2261 'list') for rows of text; 'grid' for items whose thumbnail is the thing you scan \u2014 a gallery, a logo wall, a team. Same placement rule as `preview`."
+  ),
+  reorderable: z.boolean().optional().describe(
+    "omit (\u2261 true) unless the order is PART OF THE MEANING. `false` LOCKS the list \u2014 a 'three steps' band that must stay three steps in that order, a nav whose order is semantic, a timeline. Valid only where there is a list to lock."
+  )
+});
 var fieldShape = {
   key: fieldKey.describe(
     "machine field key. \u{1F534} UNIQUE ACROSS THE WHOLE MODEL \u2014 API IDs share ONE FLAT NAMESPACE, so a field nested inside a group must NOT reuse a key used by another field or group. Every section's heading cannot be 'title'. Prefix with the section: 'hero_title', 'pricing_title', 'faq_title'. Reusing a key is refused, and if it slips through it leaves permanent errors in the editor and breaks conditional-visibility rules, which reference fields by bare key."
@@ -2124,6 +2139,29 @@ var fieldShape = {
   ),
   fields: z.array(z.lazy(() => fieldObject)).optional().describe(
     "NESTED child fields \u2014 REQUIRED for type 'group' (one nested object, a Non-Repeatable Zone like blog_hero \u2192 heading, description, hero_image) and type 'repeater' (a repeatable array of such objects, a Repeatable Zone / section-list like testimonials \u2192 quote, author). A section with repeating items is a 'repeater'; a fixed grouped block is a 'group'. Recurse to any depth \u2014 do NOT flatten zones into separate top-level fields."
+  ),
+  // ── Authoring chrome + editor behaviour ────────────────────────────────────
+  // These three already persist end-to-end and already have a panel in the dashboard's schema
+  // builder. They were unreachable from MCP for ONE reason: the OutField/toField whitelist
+  // below did not model them, so they were stripped after the model had gone to the trouble of
+  // sending them. Declaring them here is what makes the existing panel agent-writable.
+  helpText: z.string().max(500).optional().describe(
+    "one line of guidance shown UNDER this field in the editor \u2014 what to write here, not what the field is. Write it for the person typing ('Roughly 60 characters; it becomes the browser tab title'), not for a developer."
+  ),
+  showIf: z.object({
+    match: z.enum(["all", "any"]),
+    rules: z.array(
+      z.object({
+        field: z.string().describe("the BARE KEY of another field on this same model"),
+        op: z.enum(["eq", "neq", "in"]),
+        value: z.union([z.string(), z.array(z.string())])
+      })
+    )
+  }).optional().describe(
+    "conditional visibility \u2014 hide this field until another field has a given value (e.g. show `external_url` only when `link_type` is 'external'). Admin-only: it changes what an author SEES, never what is stored or delivered. Rules reference fields by BARE KEY, and the key namespace is flat, so the key must exist on this model."
+  ),
+  ui: uiObject.optional().describe(
+    "AUTHORING CHROME \u2014 how this field presents in the editor. Never a delivery effect. `preview` and `layout` are valid ONLY on a nesting field ('group', 'repeater', an 'array' with config.zones, or 'modular'); `reorderable` only where there is a LIST to lock ('repeater', an 'array' with config.zones.repeatable, or 'modular' \u2014 a 'group' holds one item). preview keys must name real children, or the write is refused with the valid keys listed. An unknown key inside `ui` is a 400, not a silent strip. Read it back with get_content_model / get_page to confirm it landed. There is deliberately no `order`: field order is the array index \u2014 use add_field's `after` to insert."
   )
 };
 var fieldObject = z.object(fieldShape);
@@ -2164,7 +2202,10 @@ function toField(f) {
   const base = {
     key: f.key,
     label: f.label,
-    ...f.required !== void 0 ? { required: f.required } : {}
+    ...f.required !== void 0 ? { required: f.required } : {},
+    ...f.helpText !== void 0 ? { helpText: f.helpText } : {},
+    ...f.showIf !== void 0 ? { showIf: f.showIf } : {},
+    ...f.ui !== void 0 ? { ui: f.ui } : {}
   };
   if (f.type === "group") {
     return { ...base, type: "array", config: { zones: { nonRepeatable: toFields(f.fields) } } };
@@ -2358,6 +2399,18 @@ function buildToolDefs(deps) {
     text: z.string().min(1).describe("the content to derive SEO metadata from"),
     context: z.string().optional().describe("optional surrounding context, e.g. the page slug")
   });
+  const connectNativeAiInput = z.object({
+    capabilities: z.array(z.string().min(1)).min(1).optional().describe(
+      "optional \u2014 any of inspect, propose, implement, cancel, question. Defaults to inspect+propose+cancel."
+    )
+  });
+  const nativeBridgeHeartbeatInput = z.object({
+    protocolVersion: z.string().min(1).describe("executor protocol version; currently '1'"),
+    capabilities: z.array(z.string().min(1)).min(1).describe(
+      "what this executor can do: any of inspect, propose, implement, cancel, question. Must include inspect, propose and cancel. An unknown value is refused, never ignored."
+    ),
+    session: z.object({ sessionId: z.string(), sessionEpoch: z.number().int().positive() }).optional().describe("the `session` from the previous response; omit on first contact to reconnect")
+  });
   const createModelInput = z.object({
     name: z.string().min(1).describe("human model name, e.g. 'Blog Post'"),
     slug: slug.describe("url-safe unique slug, e.g. 'blog-post'"),
@@ -2369,13 +2422,18 @@ function buildToolDefs(deps) {
       "the model's typed schema fields. 'group'/'repeater' NEST their child fields (any depth) \u2014 don't flatten zones into top-level fields."
     )
   });
+  const afterArg = z.string().min(1).optional().describe(
+    "OPTIONAL insertion point: the key of an existing TOP-LEVEL field to insert this one directly after. Omit to append at the end (the default, and the behaviour before this existed). Use it to put a field where an author expects it instead of at the bottom \u2014 e.g. after:'hero_title' for a subtitle. An unknown key is refused rather than silently appended."
+  );
   const addFieldInput = z.object({
     modelId: z.string().min(1).describe("id of the content model to extend"),
-    ...fieldShape
+    ...fieldShape,
+    after: afterArg
   });
   const addPageFieldInput = z.object({
     pageId: z.string().min(1).describe("id of the page to extend (from list_pages / create_page)"),
-    ...fieldShape
+    ...fieldShape,
+    after: afterArg
   });
   const uploadAssetInput = z.object({
     localPath: z.string().min(1).optional().describe("absolute path to a local file (e.g. a repo image); provide this OR url"),
@@ -2510,7 +2568,13 @@ function buildToolDefs(deps) {
     // get_site_composition counts, never a refusal. Parity: componentPropDefSchema on the server.
     required: z.boolean().optional().describe("mark the field required in the editor. An editor HINT: the API still accepts a placement that leaves it empty, and get_site_composition is what reports one."),
     helpText: z.string().max(200).optional().describe("hint shown under the control, muted (\u2264 200 chars)"),
-    placeholder: z.string().max(120).optional().describe("ghost text inside a text-ish control (\u2264 120 chars)")
+    placeholder: z.string().max(120).optional().describe("ghost text inside a text-ish control (\u2264 120 chars)"),
+    // ⚠ A STRIP SITE, exactly like OutField above: this is a `z.object`, so a key the model
+    // sends and this shape does not declare is dropped BEFORE the request leaves — a 200 with
+    // the declaration gone. `ui` rode through the backend's looseObject `config` and died here.
+    ui: uiObject.optional().describe(
+      "AUTHORING CHROME for this prop's control in the inspector \u2014 never a delivery effect, and the same object a FIELD's `ui` takes. `preview` and `layout` are valid on 'group', 'table' and 'slot' only; `reorderable` on 'table' ALONE, the one prop type whose value is a LIST (a 'group' is one object, a 'slot' one component instance). preview keys name a SUB-FIELD of this prop's config.fields and are checked against them (on a 'slot' the shape is checked but the keys cannot be \u2014 they belong to whichever component fills it). An unknown key inside `ui` is a 400, not a silent strip. Read it back with get_component: a prop whose `ui` is absent there was not stored."
+    )
   });
   const getLayoutInput = z.object({
     scope: z.enum(["global", "page"]).default("global"),
@@ -2585,7 +2649,9 @@ function buildToolDefs(deps) {
     allowedOn: allowedOn.optional(),
     description: z.string().optional(),
     blockJson: z.array(blockObject).default([]).describe("the component's block tree"),
-    props: z.array(componentPropObject).default([]).describe("overridable fields")
+    props: z.array(componentPropObject).default([]).describe(
+      "overridable fields. Each one may carry `ui` to say how its control presents in the inspector \u2014 a collapsed group, what titles and thumbnails a table's rows, whether that table's rows can be dragged at all."
+    )
   });
   const updateComponentInput = z.object({
     componentId: z.string().min(1).describe("component id (from list_components)"),
@@ -2598,7 +2664,9 @@ function buildToolDefs(deps) {
     allowedOn: allowedOn.optional().describe("REPLACES the placement allowlist"),
     description: z.string().optional(),
     blockJson: z.array(blockObject).optional().describe("REPLACES the block tree"),
-    props: z.array(componentPropObject).optional()
+    props: z.array(componentPropObject).optional().describe(
+      "REPLACES the prop array \u2014 include every prop you want to keep, WITH its stored `ui`, or that prop's authoring chrome is dropped along with the prop. Read get_component first."
+    )
   });
   const getComponentInput = z.object({
     componentId: z.string().min(1).describe("component id (from list_components)")
@@ -3016,7 +3084,7 @@ function buildToolDefs(deps) {
       def(
         "get_content_model",
         "Get a content model",
-        "Get one content model by id INCLUDING its full field schema (keys, types, nested group/repeater children). Read this before add_field so you know the existing keys.",
+        "Get one content model by id INCLUDING its full field schema (keys, types, nested group/repeater children) AND each field's stored authoring props \u2014 `helpText`, `showIf`, `ui`. Read it before add_field so you know the existing keys, and AFTER declaring `ui`/`showIf`/`helpText` as the receipt that the declaration actually landed: a prop that is missing from this response was not stored, whatever the write returned.",
         z.object({ modelId: z.string().min(1) }).shape,
         async (c, a) => ok("Content model.", await data(c, "GET", `/management/content/models/${s(a.modelId)}`))
       ),
@@ -3098,7 +3166,7 @@ function buildToolDefs(deps) {
       def(
         "get_binding_report",
         "Check what on the live site is editable",
-        "The receipt for 'is this site actually EDITABLE?'. Every release scans the built HTML for the element that renders each CMS field value; this returns what that scan found, per slot: `mode` ('text-match' = bindings guessed from rendered text, 'declared' = the template declares them), `pagesInspected`, `bound` (elements carrying a binding), and `unmatched` \u2014 per page, each path with its kind and the reason it failed (not-declared / ambiguous-text / no-element). DEPLOY FIRST: before any release there is no report and this answers pages 0, mode null, refreshRequired true. It certifies exactly one thing \u2014 that every non-empty field of every page has SOME element carrying its path. It cannot see copy that was never modelled, so diff each route's visible text against its entry values yourself before calling a page done. `builtRoutes` lists the routes the live build has HTML for (null when unknown: runtime release, >500 routes, or a report older than this field). `canvas.lane` names the live-preview lane this build gives the editor \u2014 `bridge` (the build ships BcmsDraftBridge), `draft-route` (a node runtime rendering drafts server-side) or `none`, in which case get_next_steps carries the recipe (playbook section 11); null means the report predates the field. `unaddressable` counts visible text on the live site that no field owns, as the editor's x-ray measured it against the sha now serving \u2014 the one thing `unmatched` structurally cannot see; absent means nobody has turned that control on for this build. `unaddressable` is measured PER SLOT by the editor, which frames `current`; on a promote-gated project pass slot:'current' to read it. Pass `slot` ('current' or 'staging') to read the other tree; the default is the slot this project's releases land in.",
+        "The receipt for 'is this site actually EDITABLE?'. Every release scans the built HTML for the element that renders each CMS field value; this returns what that scan found, per slot: `mode` ('text-match' = bindings guessed from rendered text, 'declared' = the template declares them), `pagesInspected`, `bound` (elements carrying a binding), and `unmatched` \u2014 per page, each path with its kind and the reason it failed (not-declared / ambiguous-text / no-element). DEPLOY FIRST: before any release there is no report and this answers pages 0, mode null, refreshRequired true. It certifies exactly one thing \u2014 that every non-empty field of every page has SOME element carrying its path. It cannot see copy that was never modelled, so diff each route's visible text against its entry values yourself before calling a page done. `builtRoutes` lists the routes the live build has HTML for (null when unknown: runtime release, >500 routes, or a report older than this field). `canvas.lane` names the live-preview lane this build gives the editor \u2014 `bridge` (the build ships BcmsDraftBridge), `draft-route` (a node runtime rendering drafts server-side) or `none`, in which case get_next_steps carries the recipe (playbook section 11); null means the report predates the field. `unaddressable` counts visible text on the live site that no field owns \u2014 the one thing `unmatched` structurally cannot see, because it only ever speaks about fields that already exist. EVERY release measures it server-side on every inspected page: `{count, pages, measuredAt, routes:[{path, count, visible, buckets:[{tag, context, chars, nodes, samples}]}]}`, where `path` is the route (the empty string is the home page), `visible` its countable characters (ornaments, skip links and the platform badge excluded from both sides) and `buckets` where the unowned text is, biggest first. Anything over `count / visible > 0.02` is copy the CMS cannot see: fix it in the SOURCE (wrap the run in an element the codemod can bind, or declare `<BcmsField path=\u2026>`), deploy, re-read \u2014 playbook section 11 has the loop. An author turning the editor's Unbound text control on posts a bare count of text NODES for the route they opened (no `visible`, no buckets); those rows are reported only for a build the release never measured, never summed with the release's characters. `skipReasons` says why pages were not inspected (`no-html`, `route-cap`, `authored-content` = the singleton lane declined the project, so NO route of it has a page), and `coverage.error` = `nothing-bound` means not one element of this build carries a binding, so the percentage beside it describes a site this build is not. `unaddressable` is measured PER SLOT; on a promote-gated project pass slot:'current' to read the tree the editor frames. Pass `slot` ('current' or 'staging') to read the other tree; the default is the slot this project's releases land in.",
         z.object({ slot: z.enum(["current", "staging"]).optional().describe("which release tree to read; defaults to the one this project deploys to") }).shape,
         async (c, a) => ok("Binding report.", await data(c, "GET", `/management/projects/current/binding-report${q({ slot: a.slot })}`))
       ),
@@ -3427,11 +3495,26 @@ function buildToolDefs(deps) {
           const model = await client.getModel(args.modelId);
           const dupes = duplicateKeys([...flatFieldKeys(model.fields), args.key]);
           if (dupes.length > 0) return fail(duplicateKeyFailure(dupes));
+          const existingFields = model.fields;
+          let at = existingFields.length;
+          if (args.after !== void 0) {
+            const idx = existingFields.findIndex(
+              (f) => f.key === args.after
+            );
+            if (idx === -1) {
+              return fail(
+                `after: '${args.after}' is not a top-level field on this model. Valid keys: ${existingFields.map((f) => `'${f.key}'`).join(", ")}. Omit \`after\` to append at the end.`
+              );
+            }
+            at = idx + 1;
+          }
+          const nextFields = [...existingFields];
+          nextFields.splice(at, 0, toField(args));
           const updated = await client.updateModel(args.modelId, {
-            fields: [...model.fields, toField(args)]
+            fields: nextFields
           });
           return ok(
-            `Added field '${args.key}' to '${updated.name}'. Model now has ${updated.fields.length} field(s).`,
+            `Added field '${args.key}' to '${updated.name}'${args.after ? ` after '${args.after}'` : ""}. Model now has ${updated.fields.length} field(s).`,
             updated
           );
         })
@@ -3446,7 +3529,10 @@ function buildToolDefs(deps) {
       },
       handler: guard(
         async (args) => withClient(async (client) => {
-          const page = await client.addPageFields(args.pageId, { addFields: [toField(args)] });
+          const page = await client.addPageFields(args.pageId, {
+            addFields: [toField(args)],
+            ...args.after !== void 0 ? { after: args.after } : {}
+          });
           return ok(
             `Added field '${args.key}' to page '${page.title}'. Page now has ${page.fields.length} field(s).`,
             page
@@ -3764,7 +3850,7 @@ function buildToolDefs(deps) {
       name: "get_component",
       config: {
         title: "Get a component (with its blockJson)",
-        description: "Get one component by id INCLUDING its blockJson tree and props. Read this before update_component so you keep the existing blocks.",
+        description: "Get one component by id INCLUDING its blockJson tree and props (with any stored `ui` authoring chrome on them). Read this before update_component so you keep the existing blocks, and after declaring field UI as the receipt that it landed \u2014 a prop absent here was not stored.",
         inputSchema: getComponentInput.shape
       },
       handler: guard(
@@ -4013,6 +4099,55 @@ ${lines.join("\n")}`, found);
         })
       )
     },
+    // ── Native bridge (executor presence) ──────────────────────────────────────
+    {
+      name: "connect_native_ai",
+      config: {
+        title: "Connect this client to the project's Native AI Connection",
+        description: "Connect this client to the project's Native AI Connection, so the dashboard shows it as an available executor. Call it ONCE when the user asks to connect \u2014 after that, ordinary tool calls on the same project keep it listed, and nothing needs to run on a timer. Idempotent. Returns the project it connected to and `presenceWindowMs`: the executor stays listed for that long after the last tool call, then drops off until the next one. THIS GRANTS NOTHING \u2014 it is presence only, and starting a run is still a human act in the dashboard. A 403 BRIDGE_GRANT_REQUIRED means this client is using a bare API key rather than an approved connection; a 400 means the connection covers the whole workspace and you must pass `projectId`.",
+        inputSchema: connectNativeAiInput.shape
+      },
+      handler: guard(
+        async (args) => withClient(async (client) => {
+          const result = await client.fetchJSON(client.url("/management/orchestration/bridge/connect"), {
+            method: "POST",
+            body: JSON.stringify({
+              protocolVersion: "1",
+              ...args.capabilities ? { capabilities: args.capabilities } : {}
+            })
+          });
+          const mins = result.presenceWindowMs ? Math.round(result.presenceWindowMs / 6e4) : null;
+          return ok(
+            `Connected to project ${result.projectId}. The dashboard now lists this client as an available executor${mins ? `; it stays listed for ${mins} minutes after the last tool call` : ""}.`,
+            result
+          );
+        })
+      )
+    },
+    {
+      name: "native_bridge_heartbeat",
+      config: {
+        title: "Register as a native bridge and report liveness",
+        description: "Register this client as a native-bridge executor for the connected project and report that it is alive. The dashboard's 'Native AI Connection' panel shows an executor as live ONLY while heartbeats keep arriving: call this again every `nextHeartbeatMs` (25s), because liveness lapses 90s after the last call and the panel then stops offering this executor. Idempotent \u2014 registration happens on the first call, so a restart or a reconnect is just another call. Echo back the `session` from the previous response so the same connection epoch is kept; omit it to reconnect, which fences the previous one. A 422 names a refused capability or protocol; it does not retry into success. THIS GRANTS NO REPOSITORY MUTATION \u2014 it is presence only, and starting a run still requires a human in the dashboard.",
+        inputSchema: nativeBridgeHeartbeatInput.shape
+      },
+      handler: guard(
+        async (args) => withClient(async (client) => {
+          const result = await client.fetchJSON(client.url("/management/orchestration/bridge/heartbeat"), {
+            method: "POST",
+            body: JSON.stringify({
+              protocolVersion: args.protocolVersion,
+              capabilities: args.capabilities,
+              ...args.session ? { session: args.session } : {}
+            })
+          });
+          return ok(
+            `Bridge ${result.liveness}. Call again within ${Math.round(result.nextHeartbeatMs / 1e3)}s to stay live.`,
+            result
+          );
+        })
+      )
+    },
     // ── Lifecycle tools (parity with the remote /mcp surface) ──────────────────
     // Media management, form submissions (leads), redirects, SEO, AEO site-files,
     // promote, and entry version history. These call the management endpoints straight
@@ -4254,7 +4389,12 @@ component placement, and the page keeps its fields, its values and its bindings.
     1. set_authoring_preference { preference: "components" }
     2. get_componentize_plan    one component per section, computed live; creates nothing. It
                                 reads this project's PUBLISHED pages, so no deploy is needed
-                                to reach it \u2014 the deploy is the last step, not the first
+                                to reach it \u2014 the deploy is the last step, not the first.
+                                On a site DERIVED at import the release hook has already run
+                                this plan in bind mode and PUBLISHED what it created, so
+                                expect ALREADY_COMPONENTIZED and skip to step 6 (publish the
+                                pages) \u2014 the lane publishes the COMPONENTS, not the placements,
+                                which are still draft blocks on the pages
     3. show the user the plan and CONFIRM \u2014 it says how many components and which pages
     4. componentize_sections    \`dryRun: true\` first, then for real; components land as DRAFTS
                                 and each placement carries \`props.bind\` to the page's field
@@ -4319,10 +4459,28 @@ lane, so every structural draft falls back to the platform renderer and its gene
 \`null\` means the report predates the field; redeploy to learn. When it is \`none\`,
 \`get_next_steps\` names the recipe for this project's framework (\`canvas-lane-missing\`), and
 \xA713 step 5c has both. The same report carries \`unaddressable\`: how much VISIBLE text on the
-live site no field owns, counted against the sha now serving when an author turns the visual
-editor's **"Unbound text"** control on \u2014 \`unmatched\` cannot see it, because it only ever speaks
-about fields that already exist. Absent means nobody has turned that control on for this build,
-not that the site is clean.
+live site no field owns \u2014 \`unmatched\` cannot see it, because it only ever speaks about fields
+that already exist. EVERY release measures it server-side, per route, with a denominator and the
+places it is (\`unaddressable.routes[]\`: \`path\`, \`count\`, \`visible\`, \`buckets[]\`). An author
+turning the editor's **"Unbound text"** control on posts a bare count of text NODES for the route
+they opened; it is reported only for a build the release never measured, and never added to
+the release's characters. Ornaments, skip links and the platform badge are excluded from both sides.
+
+**THE LOOP, and it is not optional \u2014 a deploy is not a conversion.**
+
+    1. deploy, then \`get_binding_report\`;
+    2. for each \`unaddressable.routes[]\` where \`count / visible > 0.02\`:
+       read its \`buckets\` \u2014 each one is a TAG in a LANDMARK with a sample of the copy;
+    3. fix it in the SOURCE: wrap that run of text in an element the codemod can bind (a
+       \`<span>\`, a \`<p>\`, a \`<div>\` \u2014 never a bare text node between tags), or declare it
+       yourself with \`<BcmsField path="\u2026">\`;
+    4. deploy again and re-read. Repeat until every route is under 2%.
+
+\`get_next_steps\` runs the same test and hands you the worst route with its buckets
+(\`unaddressable-copy\`). A \`coverage\` carrying \`error: "nothing-bound"\` means NOT ONE element
+of the build is bound \u2014 usually the singleton lane declined the project (\`skipReasons\`
+\`authored-content\`: its content models were authored by the repo), so the percentage beside it
+describes a site this build is not.
 
 **A site built in the CMS with NO deployed build has only that renderer** \u2014 live and in the
 editor \u2014 so the generic theme IS the site until you theme it. Theme it without a deploy:
@@ -4437,7 +4595,10 @@ still gets its own component: its own family, plus \`allowedOn: ["slug:<page>"]\
 with NO \`sectionType\` never appears in the editor's "Add a section" picker. Start from the
 builtin blueprints \`list_components\` returns (\`builtin:*\`) instead of hand-writing block JSON.
 On a DERIVED site run \`get_componentize_plan\` \u2192 \`componentize_sections\` FIRST \u2014 it does most
-of this in one call.
+of this in one call, and on a site derived at IMPORT the release hook has already run it in bind
+mode and published the components, so expect ALREADY_COMPONENTIZED \u2014 the placements it wrote are
+still DRAFT blocks on the pages, so publish the pages, then \`npx @bettercms-ai/convert
+--componentize\`.
 
 **3. The hierarchy editors see is the GROUP.** \`create_component\` and \`update_component\` take
 \`group\`: a NAME, resolved against the project's component groups and created when missing. That
@@ -4686,6 +4847,123 @@ conversion is yours to write.
 **Done means.** Whichever recipe you ran: \`get_binding_report\` reads \`mode "declared"\`,
 \`unmatched\` empty, \`bound\` above 0, \`coverage.pending\` empty, and \`canvas.lane\` is \`bridge\` or
 \`draft-route\` when the site should show structural drafts.
+
+## 14. Declare how a field LOOKS in the editor \u2014 \`ui\`, \`helpText\`, \`showIf\`
+
+You can create the schema. You can also say how it PRESENTS to the person filling it in. These
+three props ride on any field, on any field-creating tool (\`create_content_model\`,
+\`create_page\`, \`add_field\`, \`add_page_field\`), and none of them can move, reshape or hide a
+delivered value \u2014 they change editor chrome only.
+
+\`\`\`jsonc
+{ "key": "testimonials", "label": "Testimonials", "type": "repeater",
+  "ui": { "collapsed": true, "preview": { "title": "author", "media": "avatar" },
+          "layout": "grid", "reorderable": true },
+  "helpText": "Three to five. Shortest quotes read best.",
+  "fields": [ { "key": "author", ... }, { "key": "avatar", "type": "image", ... }, ... ] }
+\`\`\`
+
+- **\`helpText\`** \u2014 one line UNDER the field telling the author what to write here, not what the
+  field is. "Roughly 60 characters; it becomes the browser tab title" earns its place.
+  "The title field" does not.
+- **\`showIf\`** \u2014 hide a field until another has a value:
+  \`{match:'all',rules:[{field:'link_type',op:'eq',value:'external'}]}\`. Rules name fields by
+  BARE KEY, and the key namespace is FLAT across the model (\xA7 the duplicate-key rule), so the
+  key you reference must exist.
+- **\`ui.collapsed\`** \u2014 start a nesting field's panel closed. For long optional sections.
+- **\`ui.preview\`** \u2014 how ONE ITEM of a nesting field summarises itself when collapsed. Both
+  slots name a **CHILD FIELD KEY of that field** \u2014 not a value, not a dotted path.
+  Without it a repeater of ten testimonials reads "Item 1 \u2026 Item 10" and the author has to open
+  each one to find the one they meant. \`media\` may point at an \`image\`, \`file\` or url-ish
+  \`text\` child; the type is not constrained.
+- **\`ui.layout\`** \u2014 \`'list'\` (the default; omit it) or \`'grid'\`. Grid when the THUMBNAIL is
+  what the author scans: a gallery, a logo wall, a team. List when the words are.
+- **\`ui.reorderable\`** \u2014 omit it (\u2261 \`true\`) unless the ORDER IS PART OF THE MEANING. \`false\`
+  LOCKS the list so its items cannot be dragged: a "three steps" band that must stay three steps
+  in that order, a nav whose order is semantic, a timeline. Locking a list nobody should reorder
+  is the declaration there was previously no way to make; locking one out of tidiness takes a
+  capability away from the author, so do not set it "just in case".
+
+**Five refusals, all deliberate, all 400 with the fix in the message.**
+1. An unknown key inside \`ui\` is REJECTED, not stripped. \`ui\` is a strict object precisely so
+   that a typo is a refusal you can read instead of a 200 with your declaration gone.
+2. \`ui.preview\` on a LEAF field is refused \u2014 it summarises an item, and a leaf has no items.
+   Valid on \`group\`, \`repeater\`, an \`array\` with \`config.zones\`, or \`modular\`.
+3. \`preview.title\` / \`preview.media\` naming a key that is not a child of that field is refused,
+   and the error lists the valid child keys.
+4. \`ui.layout\` follows the same rule as \`preview\`: nesting fields only. A leaf has no items
+   to arrange.
+5. \`ui.reorderable\` is STRICTER \u2014 it needs a LIST, not merely children. Valid on \`repeater\`,
+   an \`array\` with \`config.zones.repeatable\`, or \`modular\`. A \`group\` (and a non-repeatable
+   zone) holds exactly ONE item, so there is nothing there to drag and the write is refused.
+
+**The same \`ui\` rides on COMPONENT PROPS.** \`create_component\` / \`update_component\` take it on
+each entry of \`props\`, with the placement rules the prop vocabulary implies: \`preview\` and
+\`layout\` on \`group\`, \`table\` and \`slot\`; \`reorderable\` on \`table\` ALONE, because a table is the
+only prop whose value is a list (a \`group\` is one object, a \`slot\` one component instance). A
+prop's \`preview\` keys name a SUB-FIELD from its own \`config.fields\` and are checked against
+them \u2014 except on a \`slot\`, whose children belong to whichever component fills it and therefore
+cannot be resolved at save time. \`update_component\` REPLACES the whole \`props\` array, so echo
+back each prop's stored \`ui\` or you delete it along with the prop.
+
+\`\`\`jsonc
+{ "key": "slides", "label": "Slides", "type": "table",
+  "target": { "blockId": "slider", "path": "props.slides" },
+  "ui": { "preview": { "title": "caption", "media": "image" }, "layout": "grid" },
+  "config": { "fields": [ { "key": "image", "type": "image", ... },
+                          { "key": "caption", "type": "text", ... } ] } }
+\`\`\`
+
+**THE RECEIPT \u2014 read it back.** There is no separate verification tool and no mode to flip.
+\`get_content_model\` (and \`get_page\` / \`get_component\`) return each field's \u2014 and each component
+prop's \u2014 stored \`ui\`, \`helpText\` and \`showIf\`. A prop that is ABSENT from that response was not
+stored, whatever the write returned \u2014 \xA712 rule 3, applied to this feature. Declare, then read
+back, then say it works.
+
+**No \`order\` property. Ever.** A field's order IS its index in \`fields\`. To put a new field
+somewhere other than the end, pass \`after: '<existing top-level field key>'\` to \`add_field\` /
+\`add_page_field\`; omit it and the field appends, exactly as before. \`after\` is an argument
+applied once at the write \u2014 a stored ordering prop would be a second source of truth that
+disagrees with the array the moment anyone drags a row in the builder.
+
+**Where the values come from \u2014 three tiers, in order. Stop at the first that answers.**
+
+    TIER 1  DERIVE FROM THE SITE'S SOURCE, when you have a checkout.
+            <img src={item.image}> + <h3>{item.name}</h3> inside the map over \`team\`
+              \u2192 ui.preview = { title: 'name', media: 'image' }
+            A section rendered inside a <details> or behind a "Show advanced" toggle
+              \u2192 ui.collapsed: true
+            grid-cols-* / display:grid on the wrapper of the .map \u2192 ui.layout: 'grid'
+            A FIXED-ARITY render \u2014 steps[0]/steps[1]/steps[2], or copy that names the
+            positions ("Step 1", "then", "finally") \u2192 ui.reorderable: false
+            A prop read only when another is set \u2192 showIf
+            \u{1F534} THE SERVER NEVER READS YOUR SOURCE on the add_field path. \`pull_project_source\`
+            and \`get_conversion_brief\` hand YOU the repo; this tier is work you do in your own
+            checkout before you call the tool. On a greenfield, schema-first project there is
+            no source at all \u2014 Tier 1 is vacuous and TIER 2 IS THE FLOOR.
+
+    TIER 2  DERIVE FROM THE FIELD SHAPE, when the code is silent.
+            A repeater whose children include exactly one image-ish child \u2192 that is \`media\`.
+            Its first required short-text child (name/title/heading/label) \u2192 that is \`title\`.
+            A nesting field with more than ~6 children, or one whose label reads as optional
+            ("Advanced", "Extras", "SEO overrides") \u2192 \`collapsed: true\`.
+            A repeatable whose item is MOSTLY its image (gallery, logos, team) \u2192 \`layout:
+            'grid'\`; anything whose words are the point stays 'list' \u2014 so OMIT \`layout\`.
+            \`reorderable\` HAS NO TIER-2 GUESS. The default (true) is the safe one, and
+            locking a list the user did not ask to lock takes a capability away from them.
+            Leave it absent unless Tier 1 showed you a fixed arity or the user said so.
+            Guessing here is CORRECT. A wrong preview costs one edit; asking about every
+            repeater on a 40-field schema costs the user the session.
+
+    TIER 3  ASK THE USER \u2014 only when 1 and 2 are both silent, and only for these three:
+            a) MANY fields in one panel, where the grouping and the order depend on which
+               content the user considers primary. You cannot know their priorities.
+            b) CONDITIONAL VISIBILITY (\`showIf\`). It encodes business logic \u2014 when a field is
+               irrelevant \u2014 and nothing in the code or the shape tells you that.
+            c) VARIANTS SHARING A \`sectionType\`. Their prop keys MUST match (\xA74), so a preview
+               or a rename that diverges between two variants makes a layout swap lose content.
+               Confirm the shared key set before you declare per-variant chrome.
+            Ask with AskUserQuestion, batched, once \u2014 never one field at a time.
 `;
 
 // src/prompts.ts
@@ -5191,6 +5469,108 @@ On 401/403, the MCP key needs (re)authorizing.`
       ]
     })
   );
+  server.registerPrompt(
+    "field-ui",
+    {
+      title: "Declare how fields LOOK in the editor (guided)",
+      description: "Set the authoring chrome on an existing schema \u2014 collapsed panels, what titles and thumbnails a repeater's rows, help text, conditional visibility. Derives it from your site's source where there is source, from the field shapes where there isn't, and only asks you about the three things it genuinely cannot know.",
+      argsSchema: {
+        request: z2.string().optional().describe("scope, e.g. 'the Team and Testimonials models' or 'the whole project'")
+      }
+    },
+    ({ request }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Declare the editor UI for my BetterCMS fields.${request ? ` Scope: "${request}".` : ""}
+
+Read bettercms://playbook/schema section 14 first \u2014 it has the exact prop shapes and the refusals.
+
+**What you are setting** (all of these ride on any field, on create_content_model / create_page /
+add_field / add_page_field; none of them affect delivery):
+  ui.collapsed              start a nesting field's panel closed
+  ui.preview {title,media}  which CHILD FIELD KEY titles a collapsed row, and which is its thumb
+  ui.layout 'list'|'grid'   how its items are arranged; omit for list
+  ui.reorderable            omit (= true) unless the ORDER IS THE MEANING; false LOCKS the list
+  helpText                  one line under the field: what to WRITE here
+  showIf                    hide a field until another field has a value
+
+**The same \`ui\` rides on COMPONENT PROPS** \u2014 create_component / update_component, one per entry
+of \`props\`. Placement differs because the vocabulary does: preview/layout on 'group', 'table'
+and 'slot'; reorderable on 'table' ALONE (the only prop whose value is a list). A prop's preview
+keys name a SUB-FIELD from its own config.fields. If this scope includes components, do them in
+the same pass \u2014 but note update_component REPLACES the whole props array, so read get_component
+first and echo every prop back WITH its stored ui.
+
+**Work the three tiers in order. Stop at the first that answers \u2014 do not escalate what a tier
+below already settled.**
+
+TIER 1 \u2014 DERIVE FROM SOURCE, if and only if you have a checkout of the site.
+  Read the component that renders each field. \`<img src={item.photo}>\` next to
+  \`<h3>{item.name}</h3>\` in the map over a list IS the answer: preview {title:'name',
+  media:'photo'}. A block inside \`<details>\` or behind a "Show more" is collapsed:true.
+  A \`grid-cols-*\` wrapper around the map is layout:'grid'. A FIXED-ARITY render \u2014
+  steps[0]/steps[1]/steps[2], or copy that names positions ("Step 1", "finally") \u2014 is
+  reorderable:false, and it is the ONLY evidence that earns that key.
+  \u{1F534} THE SERVER NEVER READS YOUR SOURCE. \`pull_project_source\` / \`get_conversion_brief\` hand
+  the repo to YOU; add_field does not look at it. This tier is your own reading, in your own
+  checkout, before you call any tool. ON A GREENFIELD SCHEMA-FIRST PROJECT THERE IS NO SOURCE \u2014
+  Tier 1 does not apply and TIER 2 IS THE FLOOR. Do not stall waiting for code that will
+  never exist.
+
+TIER 2 \u2014 DERIVE FROM THE FIELD SHAPE, when the code is silent or absent.
+  One image-ish child in a repeater \u2192 that is \`media\`. The first required short-text child
+  (name/title/heading/label) \u2192 that is \`title\`. More than ~6 children, or a label that reads
+  optional ("Advanced", "Extras") \u2192 collapsed:true. A repeatable whose item is mostly its
+  image (gallery, logos, team) \u2192 layout:'grid'; everything else stays list, so OMIT layout.
+  \`reorderable\` has NO Tier-2 guess \u2014 leave it absent. The default is true, and locking a
+  list the user did not ask to lock silently removes something they could do yesterday.
+  GUESS HERE otherwise. A wrong preview costs one edit; a question per repeater costs the
+  user the session.
+
+TIER 3 \u2014 ASK ME, and ONLY for these three. Batch them into ONE AskUserQuestion at the end,
+  never one field at a time:
+  a) A panel with MANY fields, where grouping and order depend on which content I treat as
+     primary \u2014 you cannot infer my priorities.
+  b) CONDITIONAL VISIBILITY (showIf) \u2014 it is business logic about when a field is irrelevant.
+     Never invent a rule.
+  c) VARIANTS SHARING A sectionType \u2014 their prop keys must match, or swapping the layout loses
+     content. Confirm the shared key set before declaring per-variant chrome.
+
+**Order of work**
+1. \`list_content_models\` / \`list_pages\`, then \`get_content_model\` / \`get_page\` for each target.
+   Note which fields ALREADY carry ui/helpText/showIf \u2014 do not overwrite a human's choice
+   without asking.
+2. Decide each field's chrome by the tiers above. Write down which tier answered; you will
+   report it.
+3. Apply. For a field that already exists, the declaration goes with the field: use the
+   dashboard or a model update \u2014 \`add_field\` APPENDS and refuses an existing key, so it is
+   the wrong tool for editing one. For a NEW field, pass ui/helpText/showIf in the same
+   \`add_field\` / \`add_page_field\` call, and pass \`after: '<existing key>'\` if it belongs
+   somewhere other than the bottom.
+4. **RECEIPT \u2014 non-negotiable.** Re-read every target with \`get_content_model\` / \`get_page\` /
+   \`get_component\` and
+   confirm the stored \`ui\` matches what you sent. A prop ABSENT from that response was NOT
+   stored, whatever the write said. Report per field: the tier that decided it, what you set,
+   and that the read-back confirmed it. Anything you could not confirm, say so plainly.
+
+**Refusals you should expect and must not work around:** an unknown key inside \`ui\` is a 400
+(it is strict on purpose \u2014 that is your typo, named); \`ui.preview\` or \`ui.layout\` on a leaf
+field is a 400 (both describe ITEMS); \`ui.reorderable\` anywhere without a LIST is a 400 \u2014 a
+\`group\` and a non-repeatable zone hold one item, so only \`repeater\`, an \`array\` with
+config.zones.repeatable, and \`modular\` take it; a preview key that is not a child of that field
+is a 400 listing the valid child keys. Fix the declaration; never retry without it and call that
+success.
+
+There is deliberately NO \`order\` property and no mode to turn on \u2014 order is the array index,
+and \`ui\` only changes editor chrome, so there is nothing to flip.`
+          }
+        }
+      ]
+    })
+  );
 }
 
 // src/server.ts