@bettercms-ai/mcp 0.38.1 → 0.41.0

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."
@@ -2118,15 +2133,65 @@ var fieldShape = {
   richText: z.boolean().optional().describe(
     "prose formatting. DEFAULTS TO TRUE for 'text': the field is created as rich text so editors can bold, link and format it on the canvas, and the API returns rich text (render with rich() from @bettercms-ai/sdk; plain() for titles and meta). Pass false for a value that is NOT prose and must stay a bare string \u2014 a URL/href, a slug, an id, an email, a phone number, a CSS class, an icon name. A link stored as rich text will not work as an href."
   ),
-  options: z.array(z.string()).optional().describe("choices when type is 'select'"),
+  options: z.array(z.union([z.string(), z.object({ label: z.string(), value: z.string() })])).optional().describe(
+    "choices when type is 'select'. A plain string, or {label, value} when the stored value differs from what the editor shows (e.g. {label:'Sold out', value:'soldOut'})."
+  ),
   config: z.record(z.string(), z.unknown()).optional().describe(
     "per-type config: reference {contentModelId}, multi-reference {contentModelId,min,max}, array {itemType: 'text'|'number'|'date'}, date {includeTime}, modular {blockSlugs: ['quote','gallery'], minItems?, maxItems?} \u2014 blockSlugs is REQUIRED, non-empty, and each slug must name an existing kind:'block' model"
   ),
   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."
+  ),
+  // ── G5: the four keys the backend field schema accepts that this whitelist stripped. ──
+  fieldsetId: z.string().min(1).optional().describe(
+    "id of one of this model's `fieldsets` (create_content_model / update_content_model). The field is shown inside that card in the editor. Editor-only: never changes what is stored or delivered."
+  ),
+  placement: z.enum(["cover", "title", "excerpt", "body", "inline", "panel"]).optional().describe(
+    "where the control sits in the entry editor: 'title' the entry's heading, 'cover' its lead image, 'excerpt' the summary, 'body' the document body, 'inline' or 'panel'. Omit to let the editor decide. Editor-only."
+  ),
+  defaultValue: z.unknown().optional().describe("the value a new entry starts with"),
+  searchable: z.boolean().optional().describe("omit (\u2261 true) to index this field for site search; false excludes it"),
+  unique: z.boolean().optional().describe(
+    "true: no two entries of this model may hold the same value (compared trimmed and case-insensitively). On a repeater child such as a variant SKU it also covers every row of every entry. Only on text, longtext, slug, email, phone, link and number. A clash is refused with 409 `unique_conflict`."
   )
 };
 var fieldObject = z.object(fieldShape);
+var urlPatternArg = z.string().nullable().optional().describe(
+  "the public URL of one entry, e.g. '/blog/:slug'. Must start with '/' and contain ':slug' exactly once ('{slug}' is refused). Drives RSS item links and the automatic 301 when an entry's slug changes. null clears it."
+);
+var fieldsetsArg = z.array(
+  z.object({
+    id: z.string().min(1),
+    name: z.string().min(1).max(60),
+    description: z.string().max(500).optional()
+  })
+).max(30).optional().describe(
+  "the model's editor cards: [{id, name, description?}], at most 30, ids unique, order = array index. `description` is one line under the card title. A field joins one with `fieldsetId`. Editor-only: never changes what is stored or delivered."
+);
+var RICH_TEXT_NOTE = "\u{1F534} A field of type 'text' is created as RICH TEXT unless you send `richText: false` on it. Send `richText: false` for every value that is not prose: a name used as a title, a URL, slug, id, SKU, email, phone, CSS class or icon name.";
 function flatFieldKeys(fields) {
   const out = [];
   const childrenOf = (f) => {
@@ -2164,7 +2229,17 @@ 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 } : {},
+    // G5: these four persist on the backend and were stripped here, like helpText once was.
+    ...f.fieldsetId !== void 0 ? { fieldsetId: f.fieldsetId } : {},
+    ...f.placement !== void 0 ? { placement: f.placement } : {},
+    ...f.defaultValue !== void 0 ? { defaultValue: f.defaultValue } : {},
+    ...f.searchable !== void 0 ? { searchable: f.searchable } : {},
+    // BE-6: a leaf key like the four above, so it rides on `base` and survives every branch.
+    ...f.unique !== void 0 ? { unique: f.unique } : {}
   };
   if (f.type === "group") {
     return { ...base, type: "array", config: { zones: { nonRepeatable: toFields(f.fields) } } };
@@ -2358,24 +2433,43 @@ 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'"),
     description: z.string().optional(),
+    urlPattern: urlPatternArg,
     kind: z.enum(["model", "block"]).optional().describe(
       "'model' (default) = a collection with its own entries. 'block' = a type that exists only to be stacked inside another model's 'modular' field \u2014 it holds no entries, and create_content_entry against it is refused. Create blocks FIRST, then the model whose modular field lists their slugs. Cannot be changed later."
     ),
     fields: z.array(fieldObject).optional().describe(
       "the model's typed schema fields. 'group'/'repeater' NEST their child fields (any depth) \u2014 don't flatten zones into top-level fields."
-    )
+    ),
+    fieldsets: fieldsetsArg
   });
+  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"),
@@ -2383,6 +2477,7 @@ function buildToolDefs(deps) {
     filename: z.string().optional().describe("override the stored filename"),
     altText: z.string().optional().describe("accessibility alt text"),
     caption: z.string().optional(),
+    transcript: z.string().max(1e5).optional().describe("video/audio only: the spoken words (\u2264 100,000 chars), published wherever the file is used"),
     folderId: z.string().optional().describe("target Media Library folder (defaults to project root)")
   });
   const createEntryInput = z.object({
@@ -2510,7 +2605,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 +2686,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 +2701,21 @@ 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 setComponentSourceInput = z.object({
+    componentId: z.string().min(1).describe("component id (from list_components)"),
+    path: z.string().min(1).max(512).describe("file path relative to the app root, e.g. src/components/sections/Hero.astro"),
+    export: z.string().min(1).max(128).optional().describe("named export that renders it; omit for a default export"),
+    kind: z.enum(["file", "section"]).optional().describe("'file' (props are this component's fields; default) or 'section' (a codemod-extracted section: props { blockId, bind, overrides, page })")
+  });
+  const submitComponentizeReceiptInput = z.object({
+    receipt: z.record(z.string(), z.unknown()).describe("The receipt `npx @bettercms-ai/convert --componentize --receipt <file>` wrote, verbatim.")
+  });
+  const clearComponentSourceInput = z.object({
+    componentId: z.string().min(1).describe("component id (from list_components)")
   });
   const getComponentInput = z.object({
     componentId: z.string().min(1).describe("component id (from list_components)")
@@ -2751,9 +2868,22 @@ function buildToolDefs(deps) {
           filename: z.string().min(1).describe("file name incl. extension"),
           altText: z.string().optional(),
           caption: z.string().optional(),
+          transcript: z.string().max(1e5).optional().describe("video/audio only: the spoken words (\u2264 100,000 chars)"),
           folderId: z.string().optional()
         }).shape,
-        async (c, a) => ok("Media asset.", await data(c, "POST", `/management/media/from-upload`, { assetId: a.assetId, uploadKey: a.uploadKey, filename: a.filename, altText: a.altText, caption: a.caption, folderId: a.folderId }))
+        async (c, a) => ok("Media asset.", await data(c, "POST", `/management/media/from-upload`, { assetId: a.assetId, uploadKey: a.uploadKey, filename: a.filename, altText: a.altText, caption: a.caption, transcript: a.transcript, folderId: a.folderId }))
+      ),
+      def(
+        "update_media",
+        "Update a media asset",
+        "Describe an existing media asset: set its alt text, caption or transcript. A transcript (video/audio only, \u2264 100,000 chars) is stored ON the asset, so every page and entry using the file publishes it \u2014 hosted pages, the .md twin, llms-full.txt and the delivery API. Pass null to clear a field. Use this after your own speech-to-text; BetterCMS does not generate transcripts.",
+        z.object({
+          assetId: z.string().min(1).describe("media asset id (from list_media / upload_asset)"),
+          altText: z.string().max(500).nullable().optional().describe("alt text; null clears"),
+          caption: z.string().max(1e3).nullable().optional().describe("caption; null clears"),
+          transcript: z.string().max(1e5).nullable().optional().describe("the spoken words; null clears. Video/audio only.")
+        }).shape,
+        async (c, a) => ok("Updated media asset.", await data(c, "PATCH", `/management/media/${encodeURIComponent(s(a.assetId))}`, { altText: a.altText, caption: a.caption, transcript: a.transcript }))
       ),
       def(
         "list_media",
@@ -3016,16 +3146,17 @@ 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)}`))
       ),
       def(
         "update_content_model",
         "Update a content model's metadata",
-        "Rename a content model or edit its description/slug (metadata only \u2014 does NOT touch fields; use add_field to extend the schema). Provide modelId plus the fields to change.",
-        z.object({ modelId: z.string().min(1), name: z.string().optional(), slug: z.string().optional(), description: z.string().optional() }).shape,
-        async (c, a) => ok("Updated content model.", await data(c, "PATCH", `/management/content/models/${s(a.modelId)}`, { name: a.name, slug: a.slug, description: a.description }))
+        "Rename a content model, edit its description/slug/urlPattern, or set its `fieldsets`. Never touches `fields`: use add_field to extend the schema. Provide modelId plus what to change. `fieldsets` REPLACES the list (send null to drop them all); then put a field in one with add_field's `fieldsetId`. `urlPattern` is the collection's entry URL, e.g. '/blog/:slug' (null clears it). A slug already used in this project and branch is refused with 409 `slug_taken`.",
+        z.object({ modelId: z.string().min(1), name: z.string().optional(), slug: z.string().optional(), description: z.string().optional(), urlPattern: urlPatternArg, fieldsets: fieldsetsArg.nullable() }).shape,
+        // `fields` is deliberately not sent: the PATCH replaces `fields` wholesale when present.
+        async (c, a) => ok("Updated content model.", await data(c, "PATCH", `/management/content/models/${s(a.modelId)}`, { name: a.name, slug: a.slug, description: a.description, urlPattern: a.urlPattern, fieldsets: a.fieldsets }))
       ),
       def(
         "get_content_types",
@@ -3098,7 +3229,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 })}`))
       ),
@@ -3379,6 +3510,8 @@ function buildToolDefs(deps) {
             slug: args.slug,
             pageType: args.pageType ?? "singleton",
             ...args.blockJson ? { blockJson: args.blockJson } : {},
+            // Cast: the SDK's ContentModelField types `options` as string[], narrower than the API,
+            // which also takes {label, value} (backend selectFieldSchema).
             ...args.fields ? { fields: args.fields.map(toField) } : {},
             ...args.metaTitle !== void 0 ? { metaTitle: args.metaTitle } : {},
             ...args.metaDescription !== void 0 ? { metaDescription: args.metaDescription } : {}
@@ -3394,7 +3527,7 @@ function buildToolDefs(deps) {
       name: "create_content_model",
       config: {
         title: "Create a content model (reusable schema)",
-        description: "Create a content model \u2014 a reusable schema for a dynamic collection (Blog, Products, Testimonials). `fields` may NEST: type 'group' = one nested object of child fields; type 'repeater' = a repeatable array of child objects. Put child fields in each group/repeater's own `fields` (any depth). Pass kind:'block' to create a BLOCK type instead \u2014 see that argument.",
+        description: "Create a content model \u2014 a reusable schema for a dynamic collection (Blog, Products, Testimonials). `fields` may NEST: type 'group' = one nested object of child fields; type 'repeater' = a repeatable array of child objects. Put child fields in each group/repeater's own `fields` (any depth). Pass kind:'block' to create a BLOCK type instead \u2014 see that argument. `fieldsets` ([{id, name}]) are the model's editor cards; a field joins one with `fieldsetId`. The slug must be unique in this project and branch: a taken one is refused with 409 `slug_taken` and free `suggestions`. " + RICH_TEXT_NOTE,
         inputSchema: createModelInput.shape
       },
       handler: guard(
@@ -3405,7 +3538,9 @@ function buildToolDefs(deps) {
             name: args.name,
             slug: args.slug,
             ...args.description !== void 0 ? { description: args.description } : {},
+            ...args.urlPattern !== void 0 ? { urlPattern: args.urlPattern } : {},
             ...args.kind !== void 0 ? { kind: args.kind } : {},
+            ...args.fieldsets !== void 0 ? { fieldsets: args.fieldsets } : {},
             fields: toFields(args.fields)
           });
           return ok(
@@ -3419,7 +3554,7 @@ function buildToolDefs(deps) {
       name: "add_field",
       config: {
         title: "Add a field to a content model",
-        description: "Append a field to an existing content model. Reads the model's current fields and adds yours (read-modify-write) \u2014 never removes existing fields. For a section/zone, add ONE 'group' (fixed block) or 'repeater' (repeating list) field carrying its child `fields` \u2014 don't add the zone's inner fields as separate top-level fields.",
+        description: "Append a field to an existing content model. Reads the model's current fields and adds yours (read-modify-write) \u2014 never removes existing fields. For a section/zone, add ONE 'group' (fixed block) or 'repeater' (repeating list) field carrying its child `fields` \u2014 don't add the zone's inner fields as separate top-level fields. `fieldsetId` puts it in one of the model's fieldsets (set them with update_content_model). " + RICH_TEXT_NOTE,
         inputSchema: addFieldInput.shape
       },
       handler: guard(
@@ -3427,11 +3562,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 +3596,12 @@ 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, {
+            // Cast: same as create_page. The SDK types `options` as string[], narrower than the
+            // API, which also takes {label, value} (backend selectFieldSchema).
+            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 +3919,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(
@@ -3967,6 +4122,61 @@ ${lines.join("\n")}`, found);
         })
       )
     },
+    {
+      name: "set_component_source",
+      config: {
+        title: "Record which file implements a component",
+        description: "Call this RIGHT AFTER you write or locate the code for a component in the app's repository. It tells BetterCMS which file renders the component, so the dashboard's Output button can build a live preview and validate it with no setup. Without it Output says no source is recorded and nothing is validated. Record ONLY a file that renders exactly this component from its own fields: a component whose props are this component's field keys (`kind: 'file'`, the default), or a section the codemod extracted with `npx @bettercms-ai/convert --componentize` \u2014 a file starting `// @bettercms-ai/convert section` whose props are `{ blockId, bind, overrides, page }` (`kind: 'section'`). Never record a different component that merely contains this markup (e.g. a card that needs a `post` object): it cannot render from these fields and validation fails. If the markup is inline in a page, extract it into a section first. `path` is relative to the app root (e.g. 'src/components/sections/Hero.astro'); `export` is the export name, omitted for a default export. Call it again if the file moves; call clear_component_source if a recorded file is wrong.",
+        inputSchema: setComponentSourceInput.shape
+      },
+      handler: guard(
+        async (args) => withClient(async (client) => {
+          const res = await client.fetchJSON(
+            client.url(`/management/components/${encodeURIComponent(args.componentId)}/preview-source`),
+            { method: "PUT", body: JSON.stringify({ path: args.path, ...args.export ? { export: args.export } : {}, ...args.kind ? { kind: args.kind } : {} }) }
+          );
+          return ok(`Recorded ${res.data.path}${res.data.export === "default" ? "" : ` (export ${res.data.export})`} as the source of component ${res.data.componentId}.`, res.data);
+        })
+      )
+    },
+    {
+      name: "submit_componentize_receipt",
+      config: {
+        title: "Record the sources a componentize run wrote",
+        description: "Record every section the componentize codemod extracted as its component's source. Call it right after `npx @bettercms-ai/convert --componentize --receipt componentize.json` (and after pushing the files): pass that receipt verbatim. Each extracted section is recorded as kind 'section' for the component with the same slug, so Output can build and validate it with no set_component_source per component. Answers which components were recorded, and any slug this project has no component for.",
+        inputSchema: submitComponentizeReceiptInput.shape
+      },
+      handler: guard(
+        async (args) => withClient(async (client) => {
+          const res = await client.fetchJSON(
+            client.url("/management/components/preview-sources/componentize-receipt"),
+            { method: "POST", body: JSON.stringify({ receipt: args.receipt }) }
+          );
+          const { recorded, unknown, invalid } = res.data;
+          return ok(
+            `Recorded ${recorded.length} section source${recorded.length === 1 ? "" : "s"}${unknown.length ? `; no component for ${unknown.join(", ")}` : ""}${invalid.length ? `; unimportable path for ${invalid.join(", ")}` : ""}.`,
+            res.data
+          );
+        })
+      )
+    },
+    {
+      name: "clear_component_source",
+      config: {
+        title: "Remove a component's recorded source file",
+        description: "Remove the file recorded as a component's source (by set_component_source or a conversion receipt). Use it when the recorded file is wrong \u2014 Output then shows no source until the right file is recorded. Safe to call when nothing is recorded.",
+        inputSchema: clearComponentSourceInput.shape
+      },
+      handler: guard(
+        async (args) => withClient(async (client) => {
+          const res = await client.fetchJSON(
+            client.url(`/management/components/${encodeURIComponent(args.componentId)}/preview-source`),
+            { method: "DELETE" }
+          );
+          return ok(res.data.cleared ? `Removed the recorded source of component ${res.data.componentId}.` : `Component ${res.data.componentId} had no recorded source.`, res.data);
+        })
+      )
+    },
     {
       name: "publish_component",
       config: {
@@ -4013,6 +4223,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
@@ -4324,10 +4583,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:
@@ -4468,6 +4745,19 @@ cluster \u2192 \`group\`. Nesting is capped at TWO levels from the prop (a \`tab
 utilities, aria attributes and alt text all survive. Never restyle while componentizing. Run
 \`componentize_sections { dryRun: true }\` and the codemod's \`--dry-run\` first.
 
+**5b. Every component's Output must render \u2014 record its SOURCE.** The dashboard's Output builds and
+validates a component from the file in the repository that renders it, and only a file whose props
+match renders it. A section the codemod extracted is such a file: after \`npx @bettercms-ai/convert
+--componentize --receipt componentize.json\`, push the files and call \`submit_componentize_receipt
+{ receipt }\` \u2014 every extracted section is recorded for the component with the same slug. A section
+you write BY HAND follows the same contract: props exactly \`{ blockId, bind, overrides, page }\`, the
+root element carries \`data-bcms-block={blockId}\`, and copy is read through \`bcmsSection(page, bind,
+overrides)\` (or \`bcmsSectionPaths\` for a flat field family like \`wrap-h2-latest\`); then call
+\`set_component_source { kind: 'section' }\`. A component module whose props ARE its fields is
+\`set_component_source\` with the default kind. NEVER record a different component that merely
+contains the markup (a card needing a \`post\` object): it cannot render from these fields and its
+validation fails every time \u2014 \`clear_component_source\` removes a wrong one.
+
 **6. The final validation is \`get_site_composition\`.** It is the receipt for "is every page
 assembled from registered components?": per page its blocks and every component placement with
 that component's status, plus site totals \u2014 unpublished, awaiting evidence, awaiting approval,
@@ -4482,6 +4772,8 @@ bulk approve, and no tool here can grant that approval. Finish with \`get_next_s
     1.  get_site_composition        the before picture
     2.  get_componentize_plan       DERIVED site only \u2014 confirm it with the user
     3.  componentize_sections       dryRun first, then for real
+    3b. npx @bettercms-ai/convert --componentize --receipt componentize.json, push,
+        then submit_componentize_receipt { receipt }   every section's Output source, ONE call
     4.  create_components           everything the plan did not cover, ONE call, each with a group
     5.  compose_pages               every page's blockJson, ONE call
     6.  update_layout { commands }  nav/footer chrome + add-component, ONE call
@@ -4694,6 +4986,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
@@ -5199,6 +5608,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