@bettercms-ai/mcp 0.70.0 → 0.71.0

package/dist/index.js

@@ -36,7 +36,27 @@ var COMPONENT_PROP_TYPES = [
   "color",
   "file",
   "icon",
-  "multiselect"
+  "multiselect",
+  // V2 schema language (F1.x). `object` is ONE nested value of named `config.fields`, stored as
+  // `{ [childKey]: value }` like the model field `object`; the six after it store what the
+  // same-named content-model FIELD stores (`location` is the V2 geopoint) and are judged by
+  // that field's validator.
+  "object",
+  "datetime",
+  "slug",
+  "email",
+  "phone",
+  "json",
+  "location",
+  // V2 leaves, each storing what the same-named content-model FIELD stores: a taxonomy string[],
+  // a rating number, a code value (`{ language?, code }` or a string).
+  "tags",
+  "rating",
+  "code",
+  // CMS items, as the same-named content-model FIELDS store them: an entry id (or a polymorphic
+  // `{ entryId, modelSlug }`), and a list of them. Delivery hydrates them like an entry's.
+  "reference",
+  "multi-reference"
 ];
 
 // ../types/src/layout-lucide-icons.ts
@@ -2277,8 +2297,8 @@ var STRUCTURE_PLAYBOOK_URI = "bettercms://playbook/structure";
 var STRUCTURE_DEFAULT_INSTRUCTION = `After you create collections or pages, organise them per the structure playbook: read ${STRUCTURE_PLAYBOOK_URI}, call suggest_content_structure (read-only), show the user its outline, then apply it with set_content_structure and the version it returned (the If-Match). A project that already has a structure keeps it: file only what you created, with move_to_folder, unless the user asks for a full re-organisation.`;
 var SKILLS_ROUTING_INSTRUCTION = "Before writing code in a repo that uses BetterCMS, explore the repo, then read the installed `bettercms` skill (`npx @bettercms-ai/install --project -y` adds it if missing): its table turns what you found into the one reference the task needs \u2014 read only that. Without the skill installed, read the same files as resources: bettercms://skill/bettercms, then bettercms://skill/<reference>.";
 var DOCK_UI_ROUTING_INSTRUCTION = "How fields and props look in the editor (groups, tabs, rows, icons, item names) is playbook \xA714 or the `field-ui` prompt: write it with update_content_model field* or update_component prop* plus ifMatch, read it back, and finish when get_next_steps reports no dock-* step.";
-var RECEIPT_FIRST_INSTRUCTION = "Start every project with get_next_steps: its `receipt` lists what is already done (`done`), what is still missing (`missing`, each item citing the count it reacted to) and the one `nextAction`. Work from that receipt instead of re-reading the site, call get_next_steps again after each batch of edits, and before you tell the user you are finished. Fix what it lists, or say why you are leaving it.";
-var NEXT_STEPS_DESCRIPTION = `Call this FIRST on a project. Returns \`receipt\` \u2014 \`done\` (live release, bound elements, conversion coverage, composed pages, published components and Layout), \`missing\`, \`nextAction\` and \`notes\` (unjudged: unknown, not done) \u2014 plus \`data\`, the unfinished items: missing meta descriptions, drafts, empty collections, unnotified forms, writes awaiting approval, unstamped bindings or sections, \`authoring-undecided\` and the Layout lane (\`layout-write-blocked\`, \`layout-field-unread\`, \`layout-locator-stale\`, \`layout-rebuild-required\`, \`chrome-duplicated\`). Each item cites its count and may carry \`payload\` {rows, total}, at most 20 rows. Call it again after a batch of edits and before telling the user you are done. \`organise-content\`: pages and collections are in no folder \u2014 read ${STRUCTURE_PLAYBOOK_URI}, call suggest_content_structure and, once the user agrees, set_content_structure.`;
+var RECEIPT_FIRST_INSTRUCTION = "Start every project with get_next_steps: its `receipt` lists what is already done (`done`), what is still missing (`missing`, each item citing the count it reacted to) and the one `nextAction`. Work from that receipt instead of re-reading the site, call get_next_steps again after each batch of edits, and before you tell the user you are finished. On an imported site you are finished only when `receipt.complete` is true: work `receipt.gate.blocking` in order, and record a gap you cannot close with editor_setup `exempt` (an allowed reason and a note), never in prose.";
+var NEXT_STEPS_DESCRIPTION = `Call this FIRST on a project. Returns \`receipt\` \u2014 \`done\` (live release, bound elements, conversion coverage, composed pages, published components and Layout), \`missing\`, \`nextAction\` and \`notes\` (unjudged: unknown, not done) \u2014 plus \`data\`, the unfinished items: missing meta descriptions, drafts, empty collections, unnotified forms, writes awaiting approval, unstamped bindings or sections, \`authoring-undecided\` and the Layout lane (\`layout-write-blocked\`, \`layout-field-unread\`, \`layout-locator-stale\`, \`layout-rebuild-required\`, \`chrome-duplicated\`). Each item cites its count and may carry \`payload\` {rows, total}, at most 20 rows. \`receipt.complete\` is the setup gate's verdict and \`receipt.gate\` its numbers: per built route the page, text, image and link coverage, \`blocking\` first, each with its \`fix\`. Call it again after each batch; you are finished only when \`complete\` is true. \`organise-content\`: pages and collections are in no folder \u2014 read ${STRUCTURE_PLAYBOOK_URI}, call suggest_content_structure and, once the user agrees, set_content_structure.`;
 var LAYOUT_CHROME_INSTRUCTION = 'When the user asks to make the navigation, footer or other site chrome editable, or get_next_steps lists a `layout-*` or `chrome-duplicated` item: this is playbook \xA711 item 3. Chrome is the project Layout, never page fields: in the source, wrap each Section in `data-bcms-layout-section` (the slot, its base slug) and mark each value `data-bcms-layout-field="layout:<sections[slug].id>:<fieldId>"`, never `data-bcms-field` inside it, then push; the strip removes the page copies, never delete them by hand. On a site BetterCMS serves, publish_layout writes Layout VALUES into the live pages; a structure change waits for a Rebuild. Never place nav, footer or modal blocks or fields on a page: the Layout (or the site\'s own layout) draws chrome, so a page copy either duplicates it or renders nowhere (get_componentize_plan reports one as LAYOUT_CHROME).';
 var CTA_BUTTON_INSTRUCTION = "A call to action is ONE `button` field (value {label, href, variant?, size?, arrow?, icon?, newTab?}), rendered with BcmsButton from @bettercms-ai/astro or @bettercms-ai/next: never a text field beside a link field. A page that already holds such a pair (primaryCtaText + primaryCtaHref) becomes one button with update_field `mergeHref`. Inside a component a CTA is a `button` block whose text and href two props target.";
 var STRUCTURE_EXAMPLE_PAYLOAD = {
@@ -2519,7 +2539,7 @@ function allKeys(fields) {
     })
   ]);
 }
-var CLEARABLE = ["helpText", "showIf", "ui", "placement", "readOnly", "lockReason"];
+var CLEARABLE = ["helpText", "showIf", "ui", "placement", "readOnly", "lockReason", "helpMore", "advanced", "recommendedMax", "openMode"];
 var SETTABLE = ["label", "required", ...CLEARABLE];
 function mergeConfig(current, patch) {
   const out = { ...current ?? {} };
@@ -2557,7 +2577,7 @@ function planFieldEdit(model, edit, callerIfMatch) {
   }
   const changes = SETTABLE.filter((k) => edit[k] !== void 0);
   if (!retype && rename === void 0 && edit.config === void 0 && changes.length === 0) {
-    return { ok: false, error: "Nothing to change: pass label, helpText, required, config, showIf, ui, placement, readOnly, lockReason, type or key." };
+    return { ok: false, error: "Nothing to change: pass label, helpText, required, config, showIf, ui, placement, readOnly, lockReason, helpMore, advanced, recommendedMax, openMode, type or key." };
   }
   const echo = helpTextEcho(edit.helpText, { label: edit.label ?? current.label, defaultValue: current.defaultValue });
   if (echo) return { ok: false, error: echo };
@@ -2673,7 +2693,8 @@ function listsTool(name, sets) {
 }
 
 // src/tool-text.ts
-var ADD_FIELD_DESCRIPTION = "Append ONE field to a content model (`modelId`) or to a page's schema (`pageId`) \u2014 additive, never overwrites; a key already in use is refused. For a section/zone add ONE 'group' (fixed block) or 'repeater' (repeating list) carrying its child `fields`, not the zone's inner fields as separate top-level fields. Pass `after` to insert it after an existing top-level field instead of at the end; `ui`, `helpText`, `showIf`, `placement` and `fieldsetId` declare how it presents in the editor \u2014 read them back with get_content_model or get_page. On a page a 'group' is stored as type 'array' with `config.zones.nonRepeatable`: entry and delivery data carry `<key>.nonRepeatable.<sub>`, while data-bcms-field paths are `<key>.<sub>`. Schema only \u2014 never places a section; use componentize_sections to turn a group into a section. `multiselect` stores a string[] of `config.options` (`allowCustom` for tags); `icon` is a BetterCMS icon name or an uploaded icon. To change a field that exists, use update_field.";
+var ADD_FIELD_DESCRIPTION = "Append ONE field to a content model (`modelId`) or to a page's schema (`pageId`) \u2014 additive, never overwrites; a key already in use is refused. For a section/zone add ONE 'group' (fixed block) or 'repeater' (repeating list) carrying its child `fields`, not the zone's inner fields as separate top-level fields. Pass `after` to insert it after an existing top-level field instead of at the end; `ui`, `helpText`, `showIf`, `placement` and `fieldsetId` declare how it presents in the editor \u2014 read them back with get_content_model or get_page. On a page a 'group' is stored as type 'array' with `config.zones.nonRepeatable`: entry and delivery data carry `<key>.nonRepeatable.<sub>`, while data-bcms-field paths are `<key>.<sub>`. Schema only \u2014 never places a section; use componentize_sections to turn a group into a section. `multiselect` stores a string[] of `config.options`; `icon` is a BetterCMS icon name or an uploaded icon. To change a field that exists, use update_field. V2 keys (object, openMode, advanced, helpMore, recommendedMax, config.scale): \xA714 of bettercms://playbook/schema.";
+var V2_LEAF_TYPES_NOTE = "`tags`: string[] taxonomy (config.options suggestions, max, allowCustom). `rating`: 0..config.max (5), step 1|0.5. `code`: {language?, code} or a string (config.languages).";
 var MOVE_STAGE_DESCRIPTION = "Move a content entry (`entryId`) or a page (`pageId`) to another editorial stage \u2014 this is how you take it OUT of review so it can be published. `workflowStage` is a stage key from get_workflow_board; pass `fromStage` to 409 if someone moved it first. Moving into the publish-gate stage is an approval and needs a publish-enabled connection. Publish afterwards with update_content_entry or update_page status:'published' \u2014 approving and publishing are deliberately two separate calls.";
 var WINDOW_NOTE = "{from?, until?}, ISO 8601 with offset: shown only between the two instants; null clears (skill publishing).";
 var WEBHOOK_EVENTS = [
@@ -2716,12 +2737,17 @@ var PARAM_TEXT = {
   lockReason: "which system owns the value (\u2264 200 chars)",
   lockClears: "as on add_field; null clears it",
   helpText: "shown under the field: its purpose, where it shows, any constraint; never its label or value. Omitted: written for you.",
+  helpMore: "longer help behind the \u24D8 next to the label, when one helpText line cannot carry it",
+  advanced: "true = a rare or developer setting: it collects in a closed 'Advanced' section",
+  recommendedMax: "a SOFT limit (characters, items or value): the editor warns past it, never refuses",
+  openMode: "object/array/group/repeater: how the value (or each row) opens: 'inline', 'drill', 'popover' or 'dialog'",
   fromBuiltin: "a builtin:* id from list_components: copies it into the project; fields you send win",
   describes: "for editors: what it is and holds; omitted: written for you",
   runtimeBundle: "instead of pageId: the server-app bundle cleanup",
   pageRef: "page id or path ('/de/about'); a bare slug only when one page has it",
   editorSetupForce: "re-run a setup already ready for the live build",
   editorSetupCheck: "true = only report the state; starts nothing",
+  editorSetupExempt: "instead of running: record setup-gate exceptions [{ route, check, reason, note }]; reason null removes one. Reasons: get_next_steps `receipt.gate`",
   pageDynamic: "a dynamic (collection template) page only",
   previewPath: "its route pattern, e.g. /blog/{slug}; null clears",
   pageModelId: "an existing collection this page lists (when it has no model yet)",
@@ -2731,7 +2757,7 @@ var PARAM_TEXT = {
   sort: "comma list, a leading - sorts descending, e.g. '-publishedAt,title'",
   page: "1-based page of `limit` rows; the response's meta says totalPages",
   locale: "language, a BCP-47 tag (zh-CN \u2192 zh-cn), one of the project's locales; null = the default",
-  translationOf: "the SOURCE's id this translates (never another translation); null unlinks. One per locale: set locale on the translation and translationOf to the source",
+  translationOf: "the SOURCE id this translates (never a translation); null unlinks. One per locale: the translation sets locale and translationOf",
   pageScheduledAt: "ISO datetime to publish this page's draft at (needs publish permission); null cancels. An edit that omits scheduledAt CANCELS a pending schedule",
   pageUnpublishAt: "ISO datetime at which the published page returns to draft; null cancels; omitting it never cancels it",
   sourceUrl: "instead of data: a public http(s) URL the server fetches and stores (private or internal addresses are refused)",
@@ -2741,8 +2767,9 @@ var PARAM_TEXT = {
   confirmedInput: "true only after the user explicitly approved adding this custom input (`ui.input`); else setting or changing one is refused input_needs_confirmation. Removing one needs no approval"
 };
 var INPUT_CONFIRMED_HEADER = "x-bcms-confirmed-input";
-var BUTTON_FIELD_NOTE = "'button' is ONE call to action, value {label, href, variant?, size?, arrow?, icon?, newTab?, rel?} (arrow:false, icon:null turn one off): never a text field beside a link field.";
-var UPDATE_FIELD_DESCRIPTION = "Change ONE existing field of a content model (`modelId`) or of a page's schema (`pageId`), addressed by `path`: its key, or dot-separated keys through groups and repeaters ('hero.title'). Set its label, helpText, required, validation `config` (merged by key; null deletes one), showIf, ui, placement, readOnly or lockReason (null clears those). The rest of the schema is written back unchanged at the version read; a 409 means it changed since, so read again. `type` changes how every stored value is read and needs allowRetype: true. `key` renames it: stored values stay under the old key, so the route answers 409 with the entry count unless allowFieldRemoval: true discards them \u2014 migrate the values first. Ask the user before a retype or a rename. A page's label + link pair (primaryCtaText + primaryCtaHref) becomes one button with `mergeHref`.";
+var BUTTON_FIELD_NOTE = "'button' is ONE call to action, value {label, href, variant? (a Button family look), size?, arrow?, icon?, newTab?, rel?} (arrow:false, icon:null off): never a text field beside a link field.";
+var LINK_VALUE_NOTE = "A link or button href: a URL string or {type: url|page|entry|email|phone|anchor|file, href, title?, newTab?, rel?, section?, ref: page/entry id}.";
+var UPDATE_FIELD_DESCRIPTION = "Change ONE existing field of a content model (`modelId`) or of a page's schema (`pageId`), addressed by `path`: its key, or dot-separated keys through groups and repeaters ('hero.title'). Set its label, helpText, required, validation `config` (merged by key; null deletes one), showIf, ui, placement, readOnly, lockReason, or the V2 helpMore, advanced, recommendedMax and openMode (null clears those). The rest of the schema is written back unchanged at the version read; a 409 means it changed since, so read again. `type` changes how every stored value is read and needs allowRetype: true. `key` renames it: stored values stay under the old key, so the route answers 409 with the entry count unless allowFieldRemoval: true discards them \u2014 migrate the values first. Ask the user before a retype or a rename. A page's label + link pair (primaryCtaText + primaryCtaHref) becomes one button with `mergeHref`.";
 var GET_SEO_DESCRIPTION = "Get the connected project's site-wide SEO settings \u2014 every key update_seo writes: seoDefaults (metaTitle, metaDescription, ogImage, twitterHandle, og, twitter, collectionSchemaTypes), siteSchema (the site's JSON-LD), robotsConfig, sitemapConfig, rssConfig, indexnowConfig and searchConfig.";
 var UPDATE_SEO_DESCRIPTION = "Set the connected project's site-wide SEO defaults and config. Each key you send is REPLACED whole (not deep-merged), so read get_seo and send the complete object. `seoDefaults` applies to every page that does not override it, and its `collectionSchemaTypes` maps a collection's model id to the schema.org type of its entries. `siteSchema` is the site's own JSON-LD (Organization/WebSite, emitted on the home page). `robotsConfig`, `sitemapConfig` and `rssConfig` shape robots.txt, sitemap.xml and the feed; `indexnowConfig` pings search engines on publish; `searchConfig` is site search. A key the plan does not include answers 403 FEATURE_LOCKED. Rebuilds the site.";
 var SEO_KEY_TEXT = {
@@ -2758,6 +2785,7 @@ var VARIANT_GROUP_NOTE = "When the component belongs to a family of looks, `vari
 var UNPROPPED_COPY_NOTE = "A `warnings` entry UNPROPPED_COPY names copy no prop targets, which nobody can edit: add a prop with a `target` for each leaf it lists.";
 var UPDATE_PAGE_IF_MATCH_NOTE = "get_page's `optimisticVersion`: the write applies only at that version, and a 409 means the page changed since, so read it again. Send it whenever you pass blockJson, which REPLACES the whole composition.";
 var SLOT_MULTIPLE_NOTE = "'slot' with config.multiple holds a list [{componentId, overrides?}] (config.maxItems, default 12, at most 50): target.path 'props.children' on a section.";
+var PROP_V2_NOTE = "Props take the fields' V2 keys (\xA714): 'object' = ONE {child: value} from config.fields, \u226410 levels (field_depth_exceeded); datetime|slug|email|phone|json|location|tags|rating|code|reference|multi-reference as that field (a reference names contentModelId, or polymorphic + allowedModelSlugs; page reads hydrate its entries); helpMore, advanced, recommendedMax, openMode, config.scale, ui.layout rows|chips|gallery, ui.preview.fallback, showIf notEmpty|empty.";
 var LAYOUT_LOCK_NOTE = "A Global field with `overridable:false` + `lockReason` (add-field `field`, update-field `patch`) refuses page overrides (LAYOUT_FIELD_NOT_OVERRIDABLE); get_layout scope page lists stored ones as `shadowed`.";
 
 // src/entry-query.ts
@@ -2922,8 +2950,15 @@ var fieldType = z.enum([
   "file",
   "sections",
   "multiselect",
-  "icon"
+  "icon",
+  // V2: ONE nested object of `fields`, kept as `object` (not normalized to zones). `toField` recurses into it.
+  "object",
+  // V2 leaves: a taxonomy string[], a rating number, a code value. The pass-through branch carries their config.
+  "tags",
+  "rating",
+  "code"
 ]);
+var OPEN_MODE_INVALID = "openMode_invalid: openMode must be one of 'inline', 'drill', 'popover', 'dialog'";
 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, underscores, and hyphens only");
 var uiObject = z.strictObject({
@@ -2931,12 +2966,13 @@ var uiObject = z.strictObject({
   preview: z.strictObject({
     title: z.string().min(1).optional().describe("CHILD KEY whose value titles a collapsed row"),
     subtitle: z.string().min(1).optional().describe("CHILD KEY whose value is the row's second line (e.g. 'level' \u2192 'Heading \xB7 h2')"),
-    media: z.string().min(1).optional().describe("CHILD KEY whose value is the row's thumbnail (image/file/url all work)")
+    media: z.string().min(1).optional().describe("CHILD KEY whose value is the row's thumbnail (image/file/url all work)"),
+    fallback: z.string().min(1).max(60).optional().describe("a literal row label while the title child is empty ('Untitled question'), not a key")
   }).optional().describe(
     "how ONE ITEM summarises itself when collapsed. Every slot names 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", "table"]).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; 'table' for up to 3 scalar columns. Same placement rule as `preview`."
+  layout: z.enum(["list", "grid", "table", "rows", "chips", "gallery"]).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; 'table' for up to 3 scalar columns. Same placement rule as `preview`. V2 'rows' | 'chips' | 'gallery' are also valid on a primitive array."
   ),
   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."
@@ -2947,7 +2983,7 @@ var uiObject = z.strictObject({
   // A refine, not an enum: 236 names inlined into every schema that carries `ui` would be paid on
   // every tools/list. The layoutIcon precedent; the server's z.enum is the guard.
   icon: z.string().min(1).max(40).refine((v) => DOCK_ICON_SET.has(v), `not a dock icon, see ${DOCK_ICONS_URI}`).optional().describe(`the branch row's icon, a name from ${DOCK_ICONS_URI}. Nesting fields only.`),
-  itemLabel: z.string().min(1).max(24).optional().describe("what ONE item is called ('Slide'): the add button, crumbs and empty state. Nesting fields only."),
+  itemLabel: z.string().min(1).max(24).optional().describe("what ONE item is called ('Slide'): the add button, crumbs and empty state. Nesting fields only. V2 itemNoun goes here."),
   input: z.object({
     name: z.string().regex(/^[a-z][a-z0-9-]{0,47}$/),
     writes: z.array(z.string().min(1).max(64)).max(16).optional()
@@ -2964,23 +3000,24 @@ var propUiObject = uiObject.extend({
     collapsed: z.boolean().optional()
   }).optional().describe("the group this prop sits in. The FIRST prop of a group defines {id, label, kind?, icon?, collapsed?}; later props send only {id}.")
 });
+var choiceOption = z.union([z.string(), z.object({ label: z.string(), value: z.string(), icon: z.string().optional(), description: z.string().optional() })]);
 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. Keys derived from an imported site may contain hyphens ('hero-h1-welcome'): address them exactly as returned."
   ),
   label: z.string().min(1).describe("human label shown in the editor"),
-  type: fieldType.describe(`field type. ${BUTTON_FIELD_NOTE}`),
+  type: fieldType.describe(`field type. ${BUTTON_FIELD_NOTE} ${LINK_VALUE_NOTE}`),
   required: z.boolean().optional().describe(
     "an entry cannot be saved without a value \u2014 set it only where the site genuinely cannot render without one"
   ),
   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.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'})."
+  options: z.array(choiceOption).optional().describe(
+    "choices when type is 'select'. A plain string, or {label, value, icon?, description?} when the stored value differs from what the editor shows (e.g. {label:'Sold out', value:'soldOut'}); icon a dock name, description one line \u2264140."
   ),
   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, timezone}, modular {blockSlugs: ['quote','gallery'], minItems?, maxItems?} \u2014 blockSlugs is REQUIRED, non-empty, and each slug must name an existing kind:'block' model; richtext {inline:true, hostTag:'h2', accept:['h2','p','b','i','u','link'], features:['bold','italic','underline','link','headings'], allowMultipleParagraphs:false} \u2014 for a field bound to ONE element on the page: `hostTag` is that element's tag and `accept` must name it, so the editor's block-style control opens already showing 'Heading 2' instead of 'Paragraph'. Name exactly ONE heading level: publish refuses an <h3> value bound to an <h2> rather than nesting one heading inside the other. Keep 'p' in `accept` or the sanitiser strips a block demoted to Paragraph"
+    "per-type config: reference {contentModelId}, multi-reference {contentModelId,min,max}, array {itemType: 'text'|'number'|'date'}, date {includeTime, timezone}, modular {blockSlugs: ['quote','gallery'], minItems?, maxItems?} \u2014 blockSlugs is REQUIRED, non-empty, and each slug must name an existing kind:'block' model; richtext {inline:true, hostTag:'h2', accept:['h2','p','b','i','u','link'], features:['bold','italic','underline','link','headings'], allowMultipleParagraphs:false} \u2014 for a field bound to ONE element on the page: `hostTag` is that element's tag and `accept` must name it, so the editor's block-style control opens already showing 'Heading 2' instead of 'Paragraph'. Name exactly ONE heading level: publish refuses an <h3> value bound to an <h2> rather than nesting one heading inside the other. Keep 'p' in `accept` or the sanitiser strips a block demoted to Paragraph; limits: text/longtext {minLength,maxLength,pattern,patternMessage}, richtext {minLength,maxLength}, number {validation:{min,max}}, array {minItems,maxItems}, tags {min,max}, rating {min,max,step}"
   ),
   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."
@@ -2996,8 +3033,8 @@ var fieldShape = {
     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", "isSet"]),
-        value: z.union([z.string(), z.array(z.string())]).optional().describe("omit for 'isSet' (the source holds any value); required for every other op")
+        op: z.enum(["eq", "neq", "in", "isSet", "notEmpty", "empty"]),
+        value: z.union([z.string(), z.array(z.string())]).optional().describe("omit for 'isSet'/'notEmpty' (the source holds any value) and 'empty' (it holds none); required for every other op")
       })
     )
   }).optional().describe(
@@ -3016,10 +3053,15 @@ var fieldShape = {
   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`."
+    "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, number, select, reference and date; on a list it means no item repeats. A clash is refused with 409 `unique_conflict`."
   ),
   readOnly: z.union([z.literal(true), z.literal("developer")]).optional().describe(PARAM_TEXT.readOnly),
-  lockReason: z.string().max(200).optional().describe(PARAM_TEXT.lockReason)
+  lockReason: z.string().max(200).optional().describe(PARAM_TEXT.lockReason),
+  // V2 schema language. Editor-only; the playbook's §14 table maps each to what the editor draws.
+  helpMore: z.string().max(2e3).optional().describe(PARAM_TEXT.helpMore),
+  advanced: z.boolean().optional().describe(PARAM_TEXT.advanced),
+  recommendedMax: z.number().int().positive().optional().describe(PARAM_TEXT.recommendedMax),
+  openMode: z.enum(["inline", "drill", "popover", "dialog"], { error: OPEN_MODE_INVALID }).optional().describe(PARAM_TEXT.openMode)
 };
 var fieldObject = z.object(fieldShape);
 var urlPatternArg = z.string().nullable().optional().describe(
@@ -3034,13 +3076,16 @@ var fieldsetsArg = z.array(
     tab: z.string().min(1).optional(),
     icon: uiObject.shape.icon,
     collapsed: z.boolean().optional(),
+    collapsible: z.boolean().optional(),
+    columns: z.union([z.literal(1), z.literal(2)]).optional(),
+    layout: z.enum(["stack", "breakpoints"]).optional(),
     // Server-owned provenance, as get_content_model returns it: an echo parses and is dropped
     // before the write (dropProvenance), never refused.
     uiOrigin: z.unknown().optional(),
     uiBefore: z.unknown().optional()
   })
 ).max(30).optional().describe(
-  "the model's editor cards: [{id, name, description?, kind?, tab?, icon?, collapsed?}], at most 30, ids unique, order = array index. kind 'group' is a disclosure, 'row' puts up to 3 short scalars on one line, 'tab' is a tab (at most 3, top-level fields only; untabbed fields stay pinned above the tabs; a group's `tab` names its tab). A field joins one with `fieldsetId`. Editor-only: never changes what is stored or delivered."
+  "the model's editor cards: [{id, name, description?, kind?, tab?, icon?, collapsed?, collapsible?, columns?:1|2, layout?:'breakpoints'}], at most 30, ids unique, order = array index. kind 'group' is a disclosure, 'row' puts up to 3 short scalars on one line, 'tab' is a tab (at most 3, top-level fields only; untabbed fields stay pinned above the tabs; a group's `tab` names its tab). A field joins one with `fieldsetId`. Editor-only: never changes what is stored or delivered."
 );
 var dropProvenance = (sets) => sets?.map(({ uiOrigin: _origin, uiBefore: _before, ...set }) => set) ?? sets;
 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.";
@@ -3126,8 +3171,16 @@ function toField(f) {
     ...f.unique !== void 0 ? { unique: f.unique } : {},
     // The developer lock: stripped here, an agent writing a model back would unlock every field.
     ...f.readOnly !== void 0 ? { readOnly: f.readOnly } : {},
-    ...f.lockReason !== void 0 ? { lockReason: f.lockReason } : {}
+    ...f.lockReason !== void 0 ? { lockReason: f.lockReason } : {},
+    // V2 editor keys: on `base` so the group/repeater rebuild cannot drop them.
+    ...f.helpMore !== void 0 ? { helpMore: f.helpMore } : {},
+    ...f.advanced !== void 0 ? { advanced: f.advanced } : {},
+    ...f.recommendedMax !== void 0 ? { recommendedMax: f.recommendedMax } : {},
+    ...f.openMode !== void 0 ? { openMode: f.openMode } : {}
   };
+  if (f.type === "object") {
+    return { ...base, type: "object", fields: toFields(f.fields) };
+  }
   if (f.type === "group") {
     return { ...base, type: "array", config: { zones: { nonRepeatable: toFields(f.fields) } } };
   }
@@ -3210,7 +3263,7 @@ var GIT_TEXT = {
 var HOSTING_TEXT = {
   list_env_vars: "The project's environment variables by NAME and scope (never a value), and `missing`: the ones the repository's .env.example declares that the project does not set. A site missing them builds and serves, then renders empty or crashes in the browser. Resolve `missing` by running `npx @bettercms-ai/cli@latest env push` in the repository: it uploads those values from the user's own .env files straight to BetterCMS, so they never pass through this conversation. Never read, print or ask the user to paste a value. When the values do not exist locally because the site reads its content from another CMS, move that content into BetterCMS instead (the bettercms skill's external-content reference). BetterCMS's own BCMS_* identifiers are supplied to every build and never need setting.",
   list_hosting_connections: "The Vercel, Netlify and Cloudflare accounts connected to this workspace (id, provider, accountLabel, status; never a token), plus `connectUrl`, the dashboard page where a person connects one. Call it before deploy_to_host. If the provider the user wants has no connection with status `ok`, give the user `connectUrl` to connect it in their browser and stop until they have: you never handle OAuth or a host token yourself.",
-  deploy_to_host: "Deploy this project to the user's own Vercel or Netlify account through their connection. BetterCMS builds the site and the host serves that build: no host CLI, no token to paste, no vercel.json rewrite; forms keep posting to the BetterCMS API. The first call creates the site on the host and makes it the project's host; a later call for the same provider redeploys that site (`redeployed: true`) instead of creating another. `connectionId` (from list_hosting_connections) defaults to the newest working one, `siteName` to the project's handle. A refusal carries a `code` and a `fixUrl` (not_connected, reconnect, pick_existing_site, grant_required, ADMIN_REQUIRED): each is fixed by the user at `fixUrl`, so relay it and stop. `deploymentQueued: false` means the project has no live build yet: deploy_project first, and that release reaches the host on its own. Never run the Vercel or Netlify CLI while a connection exists. Then poll get_host_deploy_status. Needs artifact:write, like deploy_project.",
+  deploy_to_host: "Deploy this project to the user's own Vercel or Netlify account through their connection. BetterCMS builds the site and the host serves that build (skill publishing). The first call creates the site on the host and makes it the project's host; a later call for the same provider redeploys that site (`redeployed: true`). `connectionId` (from list_hosting_connections) defaults to the newest working one, `siteName` to the project's handle. A refusal carries a `code` and a `fixUrl` (not_connected, reconnect, pick_existing_site, grant_required, ADMIN_REQUIRED): each is fixed by the user at `fixUrl`, so relay it and stop. `deploymentQueued: false` means the project has no live build yet: deploy_project first, and that release reaches the host on its own. Never run the Vercel or Netlify CLI while a connection exists. Then poll get_host_deploy_status. Needs artifact:write, like deploy_project.",
   get_host_deploy_status: "The connected project's recent deployments to Vercel, Netlify or Cloudflare, newest first: state (queued|deploying|live|failed), providerUrl, error, sha and targetName. Poll it after deploy_to_host until the newest one is `live`, whose `providerUrl` is the live URL to hand the user, or `failed`, whose `error` you read back to them."
 };
 function ok(summary, data) {
@@ -3372,7 +3425,7 @@ function buildToolDefs(deps) {
     ]).describe("block type; section/slider/tabs/columns nest child blocks"),
     id: z.string().min(1).describe("stable unique block id"),
     props: z.record(z.string(), z.unknown()).describe(
-      "per-type props: heading {text, level}; text/richtext {html} (NOT {text}), and both also take level 1-6, rendering the html AS that <hN> with inline marks kept (one line of inline copy only) \u2014 use it for a title that carries a styled span; image {src, alt}; button {text, href, variant? primary|secondary|tertiary|brand|dark|light|outline|link, size? sm|md|lg, fullWidth?, arrow? boolean, icon? ui.icon name, newTab? boolean, rel? nofollow|sponsored|ugc}; spacer {height}; video {url}; form {formId}; component {componentId, overrides?}; navbar {links:[{label,href}], logo?, cta?}; footer {columns, copyright?}; section {children: block[]}; columns {columns: block[][], gap} \u2014 a column may hold ANY block; slider {slides:[{id,children}]}; tabs {tabs:[{id,label,children}]}; collection {cardComponentId?, detailComponentId?, titleField?, excerptField?, limit?, order?, emptyText?, source? {modelId}, filters? [{field, op, value}], sort?, pinnedIds?, excludeCurrent?} \u2014 lists this page's published entries as cards, and renders ONE entry on /<page>/<entrySlug>; with `source`, that model's entries as cards on any page"
+      "per-type props: heading {text, level}; text/richtext {html} (NOT {text}), and both also take level 1-6, rendering the html AS that <hN> with inline marks kept (one line of inline copy only) \u2014 use it for a title that carries a styled span; image {src, alt}; button {text, href, variant? (hosted pages; else a Button component), size? sm|md|lg, fullWidth?, arrow? boolean, icon? ui.icon name, newTab? boolean, rel? nofollow|sponsored|ugc}; spacer {height}; video {url}; form {formId}; component {componentId, overrides?}; navbar {links:[{label,href}], logo?, cta?}; footer {columns, copyright?}; section {children: block[]}; columns {columns: block[][], gap} \u2014 a column may hold ANY block; slider {slides:[{id,children}]}; tabs {tabs:[{id,label,children}]}; collection {cardComponentId?, source? {modelId}, limit?, filters?, sort?, pinnedIds?, excludeCurrent?}: a collection's published entries as cards (every prop: skill content-modeling)"
     ),
     style: z.record(z.string(), z.unknown()).optional().describe(
       "design tokens: theme, bg (none|surface|muted|accent|dark|custom), bgCustom hex, paddingTop/paddingBottom/paddingSides px, contentWidth (narrow|default|wide|full), align, corner, shadow, borderTop/borderBottom, border (all four sides, in the text colour), hideOn [mobile|tablet|desktop], never all three. A real marketing band is a `section` block carrying bg + padding + contentWidth."
@@ -3617,10 +3670,10 @@ function buildToolDefs(deps) {
     config: z.object({
       componentIds: z.array(z.string()).optional(),
       // 'slot' allowlist
-      options: z.array(z.string()).optional(),
+      options: z.array(choiceOption).optional(),
       // 'select' — required, choices
-      // 'group'/'table' sub-shape. Typed loosely here (the server validates the full
-      // recursive shape) so a 3-level tree does not need a 3-level Zod mirror in the client.
+      // 'group'/'table'/'object' sub-shape. Typed loosely here (the server validates the full
+      // recursive shape, 10 levels at most) so a deep tree needs no Zod mirror in the client.
       fields: z.array(z.record(z.string(), z.unknown())).optional(),
       min: z.number().optional(),
       // 'number'
@@ -3641,15 +3694,20 @@ function buildToolDefs(deps) {
       match: z.enum(["all", "any"]),
       rules: z.array(z.object({
         field: z.string().min(1),
-        op: z.enum(["eq", "neq", "in", "isSet"]),
+        op: z.enum(["eq", "neq", "in", "isSet", "notEmpty", "empty"]),
         value: z.union([z.string(), z.array(z.string())]).optional()
       })).min(1).max(20)
-    }).optional().describe("show this prop only while SIBLING props (by key) match: {match:'all'|'any', rules:[{field, op:'eq'|'neq'|'in'|'isSet', value?}]}. 'isSet' takes no value. Editor-only."),
+    }).optional().describe("show this prop only while SIBLING props (by key) match: {match:'all'|'any', rules:[{field, op:'eq'|'neq'|'in'|'isSet'|'notEmpty'|'empty', value?}]}. 'isSet', 'notEmpty' and 'empty' take no value. Editor-only."),
+    // V2 editor-only keys, the model field's (playbook §14). Declared: this is a strip site.
+    helpMore: z.string().max(2e3).optional().describe(PARAM_TEXT.helpMore),
+    advanced: z.boolean().optional().describe(PARAM_TEXT.advanced),
+    recommendedMax: z.number().int().positive().optional().describe(PARAM_TEXT.recommendedMax),
+    openMode: z.enum(["inline", "drill", "popover", "dialog"], { error: OPEN_MODE_INVALID }).optional().describe("object/group/table props: how the value (or each row) opens"),
     // ⚠ 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: propUiObject.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."
+      "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', 'object' and 'slot' (`layout` 'rows'|'chips'|'gallery' also on 'multiselect', 'tags'); `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({
@@ -3728,7 +3786,7 @@ function buildToolDefs(deps) {
     description: z.string().optional().describe(PARAM_TEXT.describes),
     blockJson: z.array(blockObject).default([]).describe("the component's block tree"),
     props: z.array(componentPropObject).default([]).describe(
-      "overridable fields. DECLARE A PROP \u2014 WITH A `target` \u2014 for every string, link and image a marketer will ever touch: only the leaves a prop targets are click-to-edit. 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. 'button' is ONE unit {label, href, variant?, size?, arrow?, icon?, newTab?} on a button block's 'props', never a text prop plus a url prop. 'link' an href, 'date' YYYY-MM-DD, 'color' a hex, 'file' {url, name?}, 'icon' an icon name or an image, 'multiselect' a string[] from config.options (required). " + SLOT_MULTIPLE_NOTE
+      "overridable fields. DECLARE A PROP \u2014 WITH A `target` \u2014 for every string, link and image a marketer will ever touch: only the leaves a prop targets are click-to-edit. 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. 'button' is ONE unit {label, href, variant?, size?, arrow?, icon?, newTab?} on a button block's 'props', never a text prop plus a url prop. 'link' an href, 'date' YYYY-MM-DD, 'color' a hex, 'file' {url, name?}, 'icon' an icon name or an image, 'multiselect' a string[] from config.options (required). " + SLOT_MULTIPLE_NOTE + " " + PROP_V2_NOTE
     )
   });
   const updateComponentInput = z.object({
@@ -4273,7 +4331,7 @@ ${d.outline}` : "Proposed Content structure.", d);
       def(
         "set_binding_mode",
         "Set how the site's bindings are resolved",
-        "Switch this project between the two binding resolvers, from the NEXT release on. `declaredBindings: true` makes the annotator trust the template's own data-bcms-field / data-bcms-props and never guess from rendered text \u2014 the durable state; `false` returns to text-matching, which works once (at import, when the CMS values equal the built copy) and breaks the first time anyone edits a value. Call it ONLY after every page's copy is declared in the template: undeclared fields stop being editable. The order is push \u2192 release \u2192 get_binding_report shows mode 'text-match' with 0 unmatched \u2192 set_binding_mode \u2192 release again \u2192 get_binding_report shows mode 'declared'. Flipping back is the same call. REQUIRES artifact:write (the authority that deploys the site): this decides what every future release does to every page. On a workspace-wide connection pass `projectId`: the scope is there, but the human who authorized the connection must be able to publish THAT project or it is refused with 403 PROJECT_PUBLISH_DENIED. Playbook section 13.",
+        "Switch this project between the two binding resolvers, from the NEXT release on. `declaredBindings: true` makes the annotator trust the template's own data-bcms-field / data-bcms-props and never guess from rendered text \u2014 the durable state; `false` returns to text-matching, which holds only while the CMS values equal the built copy. Call it ONLY after every page's copy is declared in the template: undeclared fields stop being editable. The order around the flip (push, release, clean get_binding_report, flip, release, confirm): skill bindings. Flipping back is the same call. REQUIRES artifact:write (the authority that deploys the site): this decides what every future release does to every page. On a workspace-wide connection pass `projectId`: the scope is there, but the human who authorized the connection must be able to publish THAT project or it is refused with 403 PROJECT_PUBLISH_DENIED. Playbook section 13.",
         z.object({ declaredBindings: z.boolean().describe("true = trust the template's declared bindings; false = text-match (the default)") }).shape,
         async (c, a) => ok("Recorded the binding mode.", await data(c, "PATCH", `/management/projects/current/binding-mode`, { declaredBindings: a.declaredBindings }))
       ),
@@ -4408,7 +4466,7 @@ ${d.outline}` : "Proposed Content structure.", d);
       def(
         "update_page",
         "Edit a page",
-        "Edit a page: title, slug, SEO metaTitle/metaDescription, structured data (`schemaType`, `schema`), publish status (draft|published), and `blockJson` (its block composition \u2014 passing it REPLACES the whole array, so read get_page first and send its `optimisticVersion` as `ifMatch`). A `blockJson` that swaps a component block to another component comes back with `warnings` (COMPONENT_SWAP_DROPS_OVERRIDES) naming the overrides the new component does not render; they stay on the block, so swapping back restores them. It does NOT change the field SCHEMA \u2014 use add_field (pageId) / set_page_content for that. Renaming the slug keeps content intact. Publishing copies the draft blocks live in the same call \u2014 and on a singleton it publishes the page's content entry too; if the entry's workflow stage refuses, the page still goes live and `warnings` carries ENTRY_STILL_DRAFT with the entry id and the reason. STRUCTURED DATA is native SEO, never a field: leave it out and the page gets Automatic JSON-LD from its content (WebSite on the home page, Blog/CollectionPage on a collection's list page, WebPage otherwise); `schemaType` picks an explicit schema.org type whose properties are filled from the content; `schema` is pasted JSON-LD and wins over both (null clears it). " + PAGE_HEAD_NOTE + " " + SECTION_DOCTRINE,
+        "Edit a page: title, slug, SEO metaTitle/metaDescription, structured data (`schemaType`, `schema`), publish status (draft|published), and `blockJson` (its block composition \u2014 passing it REPLACES the whole array, so read get_page first and send its `optimisticVersion` as `ifMatch`). A `blockJson` that swaps a component block to another component comes back with `warnings` (COMPONENT_SWAP_DROPS_OVERRIDES: skill components). A section change the live page cannot show comes back in `holds`: saved as a draft, not live until each `action` is taken (skill publishing). It does NOT change the field SCHEMA \u2014 use add_field (pageId) / set_page_content for that. Renaming the slug keeps content intact. Publishing copies the draft blocks live in the same call \u2014 and on a singleton it publishes the page's content entry too; if that is refused, the page still goes live and `warnings` carries ENTRY_STILL_DRAFT (skill publishing). STRUCTURED DATA is native SEO, never a field: Automatic JSON-LD from the content, unless `schemaType` picks a schema.org type or pasted `schema` (wins over both, null clears it) is set (skill seo). " + PAGE_HEAD_NOTE + " " + SECTION_DOCTRINE,
         z.object({ ...headPatchShape, noindex: z.boolean().optional().describe("hide this page from search engines and site search"), pageId: z.string().min(1).describe(PARAM_TEXT.pageRef), title: z.string().optional(), slug: z.string().optional(), blockJson: z.array(blockObject).optional().describe("REPLACES the page's block composition"), metaTitle: z.string().optional(), metaDescription: z.string().optional(), schemaType: z.enum(["auto", ...SCHEMA_ORG_TYPES]).optional().describe("structured data type; 'auto' (the default) derives it from the content"), schema: z.union([z.record(z.string(), z.unknown()), z.array(z.record(z.string(), z.unknown()))]).nullable().optional().describe("custom JSON-LD; wins over schemaType; null clears it"), status: z.enum(["draft", "published"]).optional(), scheduledAt: z.string().datetime().nullable().optional().describe(PARAM_TEXT.pageScheduledAt), unpublishAt: z.string().datetime().nullable().optional().describe(PARAM_TEXT.pageUnpublishAt), locale: z.string().nullable().optional().describe(PARAM_TEXT.locale), translationOf: z.string().nullable().optional().describe(PARAM_TEXT.translationOf), ifMatch: z.number().int().min(0).optional().describe(UPDATE_PAGE_IF_MATCH_NOTE), dynamic: z.object({ previewPath: z.string().nullable().optional().describe(PARAM_TEXT.previewPath), modelId: z.string().min(1).optional().describe(PARAM_TEXT.pageModelId) }).optional().describe(PARAM_TEXT.pageDynamic) }).shape,
         async (c, a) => {
           const res = await c.fetchJSON(
@@ -4421,8 +4479,9 @@ ${d.outline}` : "Proposed Content structure.", d);
           );
           const note = res.redirectNote;
           const summary = note ? `Updated page. An existing redirect from ${note.source} already points to ${note.existingDestination}; it wasn't changed, so the old address does not redirect to the new one.` : "Updated page.";
-          return ok(res.warnings?.length ? `${summary}
-${res.warnings.join("\n")}` : summary, res.data);
+          const held = (res.holds ?? []).map((h) => `HELD ${h.reason}: ${h.message} Action: ${h.action.label}.`);
+          const lines = [summary, ...res.warnings ?? [], ...held].join("\n");
+          return ok(lines, res.holds?.length ? { ...res.data, holds: res.holds } : res.data);
         }
       ),
       // ── Code + deploy (parity with remote /mcp; needs artifact:write) ──
@@ -4569,6 +4628,10 @@ ${res.warnings.join("\n")}` : summary, res.data);
           placement: z.enum(["cover", "title", "excerpt", "body", "inline", "panel"]).nullable().optional(),
           readOnly: z.union([z.literal(true), z.literal("developer")]).nullable().optional().describe(PARAM_TEXT.lockClears),
           lockReason: z.string().max(200).nullable().optional().describe(PARAM_TEXT.lockClears),
+          helpMore: z.string().max(2e3).nullable().optional().describe(PARAM_TEXT.helpMore),
+          advanced: z.boolean().nullable().optional().describe(PARAM_TEXT.advanced),
+          recommendedMax: z.number().int().positive().nullable().optional().describe(PARAM_TEXT.recommendedMax),
+          openMode: z.enum(["inline", "drill", "popover", "dialog"], { error: OPEN_MODE_INVALID }).nullable().optional().describe(PARAM_TEXT.openMode),
           type: fieldType.optional().describe("a new type; needs allowRetype"),
           key: fieldKey.optional().describe("a new key (flat namespace, unique in the schema)"),
           allowRetype: z.boolean().optional().describe("confirm a type change, once the user has agreed"),
@@ -5073,7 +5136,7 @@ ${res.warnings.join("\n")}` : summary, res.data);
       def(
         "get_deploy_status",
         "Get deploy/build status",
-        "Get the connected project's deploy/build status: state (idle|queued|building|failed), whether it's publishing, the live commit sha, when it went live, and any build error. `editorSetup`: whether editing is set up for the live build (never or stale = call editor_setup). Poll this after deploy_project until state is idle with your sha live. `release` and `held`: skill publishing. `runtime` ({state: ok|crash-loop, restarts, oomKilled}) appears for a server app only: crash-loop means its container keeps restarting (often out of memory) though the build went live fine. Also returns `canvas.lane` (skill bindings) and `editorUrl`, the visual editor to hand the user.",
+        "Get the connected project's deploy/build status: state (idle|queued|building|failed), whether it's publishing, the live commit sha, when it went live, and any build error. `editorSetup`: whether editing is set up for the live build (never or stale = call editor_setup). Poll this after deploy_project until state is idle with your sha live. `release`, `held` and `publishes` (each `live` or `partial`): skill publishing. `runtime` ({state: ok|crash-loop, restarts, oomKilled}) appears for a server app only: crash-loop means its container keeps restarting (often out of memory) though the build went live fine. Also returns `canvas.lane` (skill bindings) and `editorUrl`, the visual editor to hand the user.",
         z.object({}).shape,
         // Flat body, no `data` envelope: `data()` read it as undefined.
         async (c) => ok("Deploy status.", await c.fetchJSON(c.url(`/management/projects/deploy-status`), { method: "GET" }))
@@ -5084,10 +5147,12 @@ ${res.warnings.join("\n")}` : summary, res.data);
         NEW_TOOL_TEXT.editor_setup,
         z.object({
           force: z.boolean().optional().describe(PARAM_TEXT.editorSetupForce),
-          check: z.boolean().optional().describe(PARAM_TEXT.editorSetupCheck)
+          check: z.boolean().optional().describe(PARAM_TEXT.editorSetupCheck),
+          exempt: z.array(z.record(z.string(), z.unknown())).optional().describe(PARAM_TEXT.editorSetupExempt)
         }).shape,
         // The route answers `{ state, … }` with no `data` envelope, so the whole body is the result.
-        async (c, a) => ok("Editor setup.", await c.fetchJSON(c.url(`/management/projects/editor-setup`), a.check === true ? { method: "GET" } : { method: "POST", body: JSON.stringify({ force: a.force }) }))
+        // `exempt` records setup-gate exceptions instead of running anything (the gate's one write).
+        async (c, a) => a.exempt ? ok("Setup gate exceptions.", await c.fetchJSON(c.url(`/management/projects/setup-gate/exceptions`), { method: "POST", body: JSON.stringify({ exempt: a.exempt }) })) : ok("Editor setup.", await c.fetchJSON(c.url(`/management/projects/editor-setup`), a.check === true ? { method: "GET" } : { method: "POST", body: JSON.stringify({ force: a.force }) }))
       ),
       // ── Deploy to the user's own host (parity with remote /mcp) ──
       // A person connects Vercel or Netlify in the dashboard; nothing here touches OAuth or a host
@@ -5240,7 +5305,7 @@ ${notes.join("\n")}` : summary, created);
       name: "add_field",
       config: {
         title: "Add a field to a content model or a page",
-        description: ADD_FIELD_DESCRIPTION + " " + RICH_TEXT_NOTE,
+        description: ADD_FIELD_DESCRIPTION + " " + V2_LEAF_TYPES_NOTE + " " + RICH_TEXT_NOTE,
         inputSchema: addFieldInput.shape
       },
       handler: guard(
@@ -5771,7 +5836,7 @@ ${notes.join("\n")}` : summary, created);
                 client.url(`/management/pages/${pageId}/meta`),
                 { method: "PATCH", body: JSON.stringify({ blockJson: page.blockJson, ...args.dryRun ? { dryRun: true } : {} }) }
               );
-              results.push({ ok: true, ...args.dryRun ? { status: "would-update" } : {}, pageId, slug: written.data?.slug ?? page.slug, path: written.data?.path, blocks: page.blockJson.length });
+              results.push({ ok: true, ...args.dryRun ? { status: "would-update" } : {}, pageId, slug: written.data?.slug ?? page.slug, path: written.data?.path, blocks: page.blockJson.length, ...written.holds?.length ? { holds: written.holds } : {} });
             } catch (err) {
               results.push({ ok: false, pageId, slug: page.slug, error: errorText(err) });
             }
@@ -6089,6 +6154,9 @@ DERIVED by \`editor_setup\`, where the componentize lane in \xA710 reuses every
     A call to action (words + link)?       -> ONE \`button\` field {label, href, variant?, size?,
                                               arrow?, icon?, newTab?} \u2014 never text + link fields
                                               (in a component: a \`button\` block, \xA73)
+    A link to a page or CMS item?          -> a \`link\` value {type:'page'|'entry', href, ref:<id>}:
+                                              the write checks ref, delivery resolves it;
+                                              a plain href string stays valid
     Site-wide nav/footer/modal?            -> the LAYOUT (get_layout/update_layout), never a
                                               page section and never one component per page
 
@@ -6239,7 +6307,7 @@ is interpolated per entry with \`{{fieldKey}}\` placeholders \u2014 \`{{title}}\
     6. content      create_content_entry / set_page_content
     7. publish      update_page status:'published'
     7b. layout      publish_layout  <- if you authored the Global Layout (nav/footer); page overrides publish with the page
-    8. check        get_next_steps, and fix what it lists
+    8. check        get_next_steps, and fix what it lists; on an imported site, until receipt.complete is true
 
 ## 8. Two ways to ship a blank site
 
@@ -6415,7 +6483,8 @@ the release's characters. Ornaments, skip links and the platform badge are exclu
     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
+(\`unaddressable-copy\`). Its \`receipt.gate\` holds EVERY built route to that bar, beside its page,
+its images and its links, and \`receipt.complete\` stays false until each route passes. 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.
@@ -6550,9 +6619,12 @@ below is one heading of that ask.
 the \`add-component\` command. CTA buttons are \`button\` BLOCKS inside the section that uses them,
 exposed as \`text\` + \`url\` props that target that ONE block \u2014 never the words as a separate text
 block beside it, or the Button panel edits nothing \u2014 variant, size and fullWidth are that block's own props and
-\`style\`. Do not hand-build a Button component: every button look you write joins the project's Button
-family (Globals/Buttons) on its own, and a new look is \`create_component\` with \`variantOf\` naming a
-Button. On a page's FIELDS a CTA is one \`button\` field (\xA72). Rich text is a \`richtext\` prop over a
+\`style\`. Do not hand-build a Button component. On a site built here every button look you write joins
+the project's Button family (Globals/Buttons) on its own, and a new look is \`create_component\` with
+\`variantOf\` naming a Button. On an IMPORTED site the family is the looks measured in the site and
+nothing you write adds to it: read it with \`list_components\`, place a look as a \`component\` block,
+and never add CSS for a look the site does not have. On a page's FIELDS a CTA is one \`button\` field
+(\xA72), whose \`variant\` picks a look of that family. Rich text is a \`richtext\` prop over a
 \`richtext\`/\`text\` block. Forms are \`create_form\` plus a \`form\` block, and form FIELDS are the
 one place the platform models \`required\`, \`placeholder\`, \`helpText\` and real \`validation\`
 (emailPolicy, min/max, phoneFormat, pattern) \u2014 put a site's validated inputs there. Cards,
@@ -6880,6 +6952,15 @@ conversion is yours to write.
    fetch the live URL cache-busted (RECEIPTS in \xA711: publish and deploy are separate claims).
    \`get_next_steps\` keeps reporting the gap until every one of these holds.
 
+**The finish line is \`receipt.complete\`.** \`get_next_steps\` answers it from the setup gate
+(\`receipt.gate\`): every route of the live build has a published page (or entry), one page only,
+at most 2% of its visible text unowned, every image a field's and 95% of its links. \`blocking\`
+lists what fails, worst route first, each with the \`fix\` call to run; a null \`fix\` is the
+user's to decide. A gap left on purpose is RECORDED, \`editor_setup { exempt: [{ route, check,
+reason, note }] }\`, with a reason \`allowedExceptions\` lists for that check. Running out of time,
+context or patience is in \`neverExceptions\`: it is refused, and telling the user why instead
+leaves the gate incomplete. \`bettercms init\` reads the same gate when you exit and prints it.
+
 **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.
@@ -6969,7 +7050,7 @@ FIELD never takes \`ui.group\`; it joins a fieldset with \`fieldsetId\`.
 - **leaf** \u2014 one field, one control. Nothing to declare; \`ui.control\` only when the default is wrong.
 - **group** \u2014 a \`kind: 'group'\` fieldset (a prop: \`ui.group\`): a disclosure that shows two values
   when closed. \`collapsed: true\` starts it closed.
-- **row** \u2014 a \`kind: 'row'\` fieldset: at most 3 short scalars (number, color, boolean, date,
+- **row** \u2014 a \`kind: 'row'\` fieldset: at most 3 short scalars (number, rating, color, boolean, date,
   datetime, select) on one line. No \`ui.control\` on a row member.
 - **branch** \u2014 a nesting field drawn as a drill-in row with its \`ui.icon\` and a summary.
 - **list** \u2014 repeatable items named by \`ui.itemLabel\` and \`ui.preview\`.
@@ -7002,6 +7083,32 @@ Importance orders a screen: required fields first, then array order.
 | CTA | one \`kind:'group'\` fieldset holding the heading, text and ONE \`button\` field, \`icon:'launch'\` |
 | Dimensions | one \`kind:'row'\` fieldset of up to 3 numbers (width, height, gap) |
 
+**The V2 schema language \u2014 to get X in the editor, write Y.** Every key below is editor-only and stored as sent, EXCEPT \`type: 'object'\`: it changes the stored and delivered value to \`{ [childKey]: value }\` (a \`group\` carries \`<key>.nonRepeatable.<sub>\` instead), and codegen types it as a nested object, so swapping group \u2194 object moves values and templates.
+
+| To get this in the editor | Write this |
+|---|---|
+| A section that starts closed / a static heading | fieldset \`collapsed: true\` / \`collapsible: false\` |
+| Two short fields side by side | fieldset \`columns: 2\` |
+| One Desktop \xB7 Tablet \xB7 Phone switcher | three \`type: 'object'\` fields named \`desktop\`, \`tablet\`, \`phone\`, each with \`fieldsetId\` pointing at ONE fieldset with \`layout: 'breakpoints'\` |
+| A small inset of 2\u20133 fields, or a row that opens its own screen | \`type: 'object'\` with \`fields\`; \`openMode: 'inline', 'drill', 'popover', 'dialog'\` |
+| List rows that drill in instead of expanding | \`openMode: 'drill'\` on the array (or repeater) |
+| Tiles instead of rows | \`ui.layout: 'grid'\` on a list of objects (V2 \`arrayLayout: 'grid'\`); a primitive image array takes \`'gallery'\` |
+| BetterCMS-only list layouts | \`ui.layout: 'rows'\` (\u2261 'list'), \`'chips'\`, \`'gallery'\`, also on a primitive array. Never chips for a feature list: chips cut long lines |
+| A size capsule with numeric steps | \`type: 'number'\`, \`config.scale: { steps: {min, max, step} or [{value, label}], units?, presets? }\`. Token (string) steps and an \`allowCustom\` object are refused (\`scale_invalid\`): use numeric steps and \`allowCustom: true\` |
+| Help under the label / longer help behind \u24D8 | \`helpText\` / \`helpMore\` |
+| Calm defaults for rare settings | \`advanced: true\` |
+| A soft length warning (amber, never a refusal) | \`recommendedMax: 60\` |
+| A marketer cannot change it | \`readOnly: 'developer'\` plus \`lockReason\` |
+| A field that shows only sometimes | \`showIf\` (it SHOWS the field): ops \`eq\`, \`neq\`, \`in\`, \`isSet\`, \`notEmpty\`, \`empty\` |
+| A good row title and thumbnail | \`ui.preview: { title, subtitle, media, fallback }\` (\`fallback\` is a literal label) |
+| Labels that classify or filter (topics, keywords), never a feature list | \`type: 'tags'\`: a string[], trimmed, de-duplicated, each \u226464 characters; \`config.options\` are suggestions, \`config.max\`, \`config.allowCustom: false\` closes the list (\`tags_value_invalid\`) |
+| A star rating | \`type: 'rating'\`: a number from 0 to \`config.max\` (5), \`config.step\` 1 or 0.5 (\`rating_value_invalid\`) |
+| A code snippet | \`type: 'code'\`: \`{ language?, code }\` or a string; \`config.language\` default, \`config.languages\` allowlist (\`code_value_invalid\`) |
+| "Add question" instead of "Add item" | \`ui.itemLabel: 'Question'\` (V2 \`itemNoun\`; there is no itemNoun key) |
+| The same section as a component (the dock edits a page section through its props) | the same keys on its \`props\`: \`type: 'object'\` with \`config.fields\` (\`group\` and \`table\` too, 10 levels), \`datetime\`, \`slug\`, \`email\`, \`phone\`, \`json\`, \`location\`, \`tags\`, \`rating\`, \`code\`, plus the two CMS-item types (\`reference\`, \`multi-reference\`: \`config.contentModelId\` or \`polymorphic\` + \`allowedModelSlugs\`; page reads hydrate them, a text slot shows the title), and every key above except fieldsets (props group with \`ui.group\`) |
+
+An unknown \`openMode\` is refused with \`openMode_invalid\`, one on a leaf \`openMode_leaf\`; a bad \`config.scale\` with \`scale_invalid\`; more than 10 nested field levels with \`field_depth_exceeded\`. update_field sets and clears (null) helpMore, advanced, recommendedMax and openMode on an existing field.
+
 **Tabs.** A \`kind: 'tab'\` fieldset is a tab:
 - at most **3** tabs, names at most 20 characters and unique;
 - top-level fields only: tabs never nest and props never take them;
@@ -7250,8 +7357,8 @@ error-prone, so go slow and confirm. Never guess the layout.
    the same prop keys across a family or a swap drops content.
 4. **Props** \u2014 declare only what should really be editable:
    { key, label, target: { blockId, path },
-   type: text|richtext|image|url|boolean|number|select|group|table|slot|form|link|button|date|color|file|icon|multiselect }.
-   'select'/'multiselect' need config.options; 'group'/'table' need config.fields; a 'button'
+   type: text|richtext|image|url|boolean|number|select|group|table|slot|form|link|button|date|color|file|icon|multiselect|object|datetime|slug|email|phone|json|location|tags|rating|code|reference|multi-reference }.
+   'select'/'multiselect' need config.options; 'group'/'table'/'object' need config.fields; a 'button'
    is ONE prop on a button block's 'props', never a label prop plus a url prop; 'slot' holds ONE nested component (a list with config.multiple);
    'form' holds ONE Form document \u2014 point target.path at 'props' on an empty form block and set
    defaultValue to {formId}. Never re-declare a form's FIELDS as props: the Form document owns
@@ -7710,8 +7817,10 @@ Read bettercms://playbook/schema section 11 first, then work this order:
    scale, nav position/background, footer surface as DTCG {"$type","$value"} entries) and
    redeploy, or structural draft previews render in a generic theme, not this site's design.
 5. VERIFY \u2014 call get_next_steps and fix what it lists (it knows about missing manifests,
-   a setup that has not run, and placed-but-unpublished components), or tell me why
-   an item is being left.
+   a setup that has not run, and placed-but-unpublished components). You are finished only
+   when its receipt.complete is true: work receipt.gate.blocking top down, and record an item
+   you cannot close with editor_setup { exempt } under an allowed reason. Telling me why is
+   not an exception.
 
 On 401/403, the MCP key needs (re)authorizing.`
           }