@bettercms-ai/mcp 0.68.1 → 0.69.0

package/dist/index.js

@@ -27,7 +27,16 @@ var COMPONENT_PROP_TYPES = [
   "group",
   "table",
   "slot",
-  "form"
+  "form",
+  // The seven below each store what the same-named content-model FIELD stores (`icon` and
+  // `multiselect` have no field twin; see the value notes on ComponentPropDef.type).
+  "link",
+  "button",
+  "date",
+  "color",
+  "file",
+  "icon",
+  "multiselect"
 ];
 
 // ../types/src/layout-lucide-icons.ts
@@ -2510,7 +2519,7 @@ function allKeys(fields) {
     })
   ]);
 }
-var CLEARABLE = ["helpText", "showIf", "ui", "placement"];
+var CLEARABLE = ["helpText", "showIf", "ui", "placement", "readOnly", "lockReason"];
 var SETTABLE = ["label", "required", ...CLEARABLE];
 function mergeConfig(current, patch) {
   const out = { ...current ?? {} };
@@ -2548,7 +2557,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, type or key." };
+    return { ok: false, error: "Nothing to change: pass label, helpText, required, config, showIf, ui, placement, readOnly, lockReason, type or key." };
   }
   const echo = helpTextEcho(edit.helpText, { label: edit.label ?? current.label, defaultValue: current.defaultValue });
   if (echo) return { ok: false, error: echo };
@@ -2601,6 +2610,7 @@ var LISTING_TAIL = /* @__PURE__ */ new Set([
   "extract_component",
   "list_extraction_candidates",
   "create_deploy_upload",
+  "import_redirects",
   "set_authoring_preference",
   "set_media_delivery",
   "delete_form_submission",
@@ -2679,7 +2689,7 @@ var NEW_TOOL_TEXT = {
   discard_draft: "Throw away unpublished edits to an entry (`entryId`) or a page (`pageId`) \u2014 exactly one: the draft returns to exactly what is live and `pendingChanges` becomes false. A page resets its blockJson and its published Layout overrides. 409 no_published_version means it was never published (delete it instead). Pass ifMatch (optimisticVersion) to refuse if it changed since you read it.",
   give_feedback: "Tell the BetterCMS team about a tool that failed, a capability you needed and did not have, or docs that misled you. Opens a ticket for the team; nothing in the project changes. Name the `tool`, and paste the request and response into `context`. Never include secrets or personal data.",
   publish_entries: "Publish or unpublish many entries and pages in ONE call (up to 100 ids of each; pages publish only). Needs a publish-enabled connection, and each item still passes its own gates (editorial stage, required fields). Nothing stops the run: the result lists what changed (`published` or `unpublished`) and every refusal in `failed` with its reason. A publish answers 202 with the routes being rebuilt.",
-  create_content_entries: "Create up to 200 DRAFT entries of one collection in ONE call, each {slug?, data} as create_content_entry takes it. Every row reports `created` (with id and slug) or `failed` (with the error), a failure does not stop the others, and `meta` counts both. Publish afterwards with publish_entries.",
+  create_content_entries: "Create up to 200 DRAFT entries of one collection in ONE call, each {slug?, data} as create_content_entry takes it. Every row reports `created` (with id and slug) or `failed` (with the error), a failure does not stop the others, and `meta` counts them. A row with `externalKey` is safe to send again: its entry is `updated` (draft only), or `unchanged` when the row is the same. A row setting a developer-locked field fails (FIELD_LOCKED). Publish afterwards with publish_entries.",
   translate_entry: "Create an entry's `targetLocale` translation with AI (uses AI credits: 402/403 when out or not on the plan). Text and longtext fields are translated; rich text and documents are copied for you to translate; the rest is copied. The new entry is a DRAFT with `locale` set and `translationOf` = the source; `meta` lists translated and copied keys. `targetLocale` must be one of the project's locales; 409 locale_conflict means that translation exists, so edit it instead.",
   list_webhooks: "List the project's outgoing webhooks: name, url, events, whether active, and delivery health (total, failed, last attempt). Signing secrets are never returned.",
   create_webhook: "Create an outgoing webhook: BetterCMS POSTs each subscribed event to your https `url`, signed with HMAC-SHA256 in X-BetterCMS-Signature. The response carries the signing `secret` ONCE: store it now. `test: true` also sends a sample delivery. Payloads carry ids and metadata, never the content: fetch it from the API. A receiver that writes back on content.updated loops unless it skips its own writes.",
@@ -2689,11 +2699,21 @@ var NEW_TOOL_TEXT = {
   search_docs: "Search the BetterCMS documentation. Returns the best pages (title, url, breadcrumbs, snippet). Use it before guessing how a feature works; `meta.unavailable` means docs search is down right now.",
   generate_image: "Generate an image with AI and add it to the Media Library (5 AI credits; free with the workspace's own Together key). `width`/`height` are 256-1440 in multiples of 16 (default 1024x768). Returns the new asset (id, url, altText): use the url as an 'image' field value. Always set `altText`.",
   refresh_search_index: "Tell search engines and site search about published changes; costs nothing. action 'indexnow' submits `urls` (this site's own, up to 1000) to IndexNow, or every change since the last submission when omitted. action 'reindex' rebuilds the project's site-search index. 503 means the index is unreachable: try again later.",
+  import_redirects: "Bulk-create redirects for a migration, from `rows` or from `text` in `format` (our CSV export, a Netlify `_redirects` file, or a vercel.json). Call it with `dryRun: true` FIRST: nothing is written and each row comes back `would-create`, `existing` or `skipped` with a reason. Rows get create_redirect's rules. Max 5000.",
   editor_setup: "Make the live build editable. A build imports only SEO/meta, media, brand and the models bcms-content.json declares; this derives the rest from the live release: pages, collections, forms, bindings, button and section components (when the authoring preference is components), Component Groups and the Content sidebar. Run it after an import or a rebuild, before the conversion brief. Idempotent: `ready` when it already ran for the live sha, else it starts (`running`; poll with `check: true` or get_deploy_status `editorSetup`). `state`: never or stale (run it), running, ready, failed. 409 = nothing is live yet: deploy first. Then get_next_steps.",
   transform_image: "Edit an existing Media Library image with an instruction (e.g. 'remove the background', 'make it dusk'); the result is saved as a NEW asset and the original is kept (5 AI credits). Returns the new asset (id, url, altText)."
 };
 var DELETE_PAGE_RUNTIME_BUNDLE = " Or, with no pageId, `runtimeBundle`: 'report' lists the duplicate pages derived from a server app's own bundle (`app/` folders); 'apply' retires them and their empty folders.";
+var FIELD_LOCKED_NOTE = "A readOnly 'developer' field keeps its stored value: changing or omitting it without schema access is 403 FIELD_LOCKED.";
 var PARAM_TEXT = {
+  dryRun: "validates and reports what would be written; writes nothing",
+  externalKey: "id in the source system; sent again, it updates that entry's draft or leaves it unchanged",
+  upsertSource: "source URL, kept with the entry",
+  upsertRunId: "your run's id, kept with the entry",
+  externalKeyFilter: "exact externalKey an entry was created with",
+  readOnly: "'developer' = the value and this lock change only with schema access (needs lockReason); true = an editor marker",
+  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.",
   describes: "for editors: what it is and holds; omitted: written for you",
   runtimeBundle: "instead of pageId: the server-app bundle cleanup",
@@ -2719,14 +2739,14 @@ 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?} (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 or placement (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?, 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 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 = {
   seoDefaults: "site-wide meta defaults every page inherits",
   siteSchema: "the site's JSON-LD: an object or an array of objects",
-  robotsConfig: "robots.txt: 'auto', or 'custom' with its text",
+  robotsConfig: "robots.txt: 'auto' (`disallow` names AI crawlers to block), or 'custom' with its text",
   sitemapConfig: "sitemap.xml: generated ('auto') or 'custom', defaults and extra URLs",
   rssConfig: "the RSS feed on or off",
   indexnowConfig: "IndexNow on publish, minus URL patterns to leave out",
@@ -2753,7 +2773,7 @@ function whereToQuery(where) {
 }
 function entryListSearch(args) {
   const q = new URLSearchParams();
-  for (const key of ["modelId", "pageId", "status"]) if (args[key]) q.set(key, String(args[key]));
+  for (const key of ["modelId", "pageId", "status", "externalKey"]) if (args[key]) q.set(key, String(args[key]));
   for (const [k, v] of whereToQuery(args.where)) q.append(k, v);
   for (const key of ["sort", "page", "limit"]) if (args[key] !== void 0 && args[key] !== null) q.set(key, String(args[key]));
   if (args.detail !== true) q.set("select", "summary");
@@ -2954,7 +2974,7 @@ var fieldShape = {
     "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; 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"
   ),
   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."
@@ -2970,8 +2990,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"]),
-        value: z.union([z.string(), z.array(z.string())])
+        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")
       })
     )
   }).optional().describe(
@@ -2991,7 +3011,9 @@ var fieldShape = {
   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`."
-  )
+  ),
+  readOnly: z.union([z.literal(true), z.literal("developer")]).optional().describe(PARAM_TEXT.readOnly),
+  lockReason: z.string().max(200).optional().describe(PARAM_TEXT.lockReason)
 };
 var fieldObject = z.object(fieldShape);
 var urlPatternArg = z.string().nullable().optional().describe(
@@ -3016,7 +3038,7 @@ var fieldsetsArg = z.array(
 );
 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.";
-var SCHEMA_ORG_TYPES = ["WebPage", "AboutPage", "ContactPage", "CollectionPage", "Blog", "BlogPosting", "Article", "Product", "FAQPage", "Event", "Organization", "LocalBusiness"];
+var SCHEMA_ORG_TYPES = ["WebPage", "AboutPage", "ContactPage", "CollectionPage", "Blog", "BlogPosting", "Article", "Product", "FAQPage", "Event", "Organization", "LocalBusiness", "JobPosting", "Course", "Recipe", "HowTo", "Service", "Person", "VideoObject"];
 var changefreq = z.enum(["auto", "always", "hourly", "daily", "weekly", "monthly", "yearly", "never"]);
 var jsonObject = z.record(z.string(), z.unknown());
 var seoPatchShape = {
@@ -3030,7 +3052,7 @@ var seoPatchShape = {
     collectionSchemaTypes: z.record(z.string().min(1).max(64), z.enum(SCHEMA_ORG_TYPES)).optional()
   }).optional().describe(SEO_KEY_TEXT.seoDefaults),
   siteSchema: z.union([jsonObject, z.array(jsonObject)]).optional().describe(SEO_KEY_TEXT.siteSchema),
-  robotsConfig: z.object({ mode: z.enum(["auto", "custom"]), custom: z.string().max(1e4).optional() }).optional().describe(SEO_KEY_TEXT.robotsConfig),
+  robotsConfig: z.object({ mode: z.enum(["auto", "custom"]), custom: z.string().max(1e4).optional(), disallow: z.array(z.enum(["GPTBot", "OAI-SearchBot", "ChatGPT-User", "ClaudeBot", "Claude-Web", "anthropic-ai", "PerplexityBot", "Google-Extended", "CCBot", "Bytespider", "Applebot-Extended", "Amazonbot", "Meta-ExternalAgent"])).max(32).optional() }).optional().describe(SEO_KEY_TEXT.robotsConfig),
   sitemapConfig: z.object({
     enabled: z.boolean(),
     mode: z.enum(["auto", "custom"]).optional(),
@@ -3079,6 +3101,8 @@ function proseType(f) {
 }
 var confirmedHeaders = (confirmed) => confirmed === true ? { [INPUT_CONFIRMED_HEADER]: "true" } : {};
 var withHeaders = (headers) => Object.keys(headers).length > 0 ? { headers } : {};
+var DRY_RUN_SUMMARY = "Dry run: nothing was written.";
+var dryRunOf = async (client, method, path, body, headers = {}) => ok(DRY_RUN_SUMMARY, await client.fetchJSON(client.url(path), { method, body: JSON.stringify({ ...body, dryRun: true }), ...withHeaders(headers) }));
 function toField(f) {
   const base = {
     key: f.key,
@@ -3093,7 +3117,10 @@ function toField(f) {
     ...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 } : {}
+    ...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 } : {}
   };
   if (f.type === "group") {
     return { ...base, type: "array", config: { zones: { nonRepeatable: toFields(f.fields) } } };
@@ -3338,7 +3365,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}; 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?} \u2014 lists this page's published entries as cards, and renders ONE entry on /<page>/<entrySlug>"
+      "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"
     ),
     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). A real marketing band is a `section` block carrying bg + padding + contentWidth."
@@ -3391,7 +3418,8 @@ function buildToolDefs(deps) {
     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
+    fieldsets: fieldsetsArg,
+    dryRun: z.boolean().optional().describe(PARAM_TEXT.dryRun)
   });
   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."
@@ -3399,6 +3427,7 @@ function buildToolDefs(deps) {
   const addFieldInput = z.object({
     modelId: z.string().min(1).optional().describe("the content model to extend (from list_content_models); or send pageId"),
     pageId: z.string().min(1).optional().describe("instead of modelId: the page whose schema to extend (from list_pages / create_page)"),
+    dryRun: z.boolean().optional().describe(PARAM_TEXT.dryRun),
     ...fieldShape,
     after: afterArg,
     confirmed: z.boolean().optional().describe(PARAM_TEXT.confirmedInput)
@@ -3413,13 +3442,20 @@ function buildToolDefs(deps) {
     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 upsertShape = {
+    externalKey: z.string().min(1).max(255).optional().describe(PARAM_TEXT.externalKey),
+    source: z.string().max(2048).optional().describe(PARAM_TEXT.upsertSource),
+    runId: z.string().max(100).optional().describe(PARAM_TEXT.upsertRunId)
+  };
   const createEntryInput = z.object({
     contentModelId: z.string().min(1).describe("id of the model this entry belongs to"),
     slug: slug.optional(),
     status: z.enum(["draft", "published"]).optional().describe("defaults to draft"),
     data: z.record(z.string(), z.unknown()).optional().describe("field values keyed by field key"),
     locale: z.string().nullable().optional().describe(PARAM_TEXT.locale),
-    translationOf: z.string().nullable().optional().describe(PARAM_TEXT.translationOf)
+    translationOf: z.string().nullable().optional().describe(PARAM_TEXT.translationOf),
+    dryRun: z.boolean().optional().describe(PARAM_TEXT.dryRun),
+    ...upsertShape
   });
   const getPageInput = z.object({
     pageId: z.string().min(1).describe(PARAM_TEXT.pageRef)
@@ -3439,6 +3475,7 @@ function buildToolDefs(deps) {
     modelId: z.string().optional().describe("filter by content model id"),
     pageId: z.string().optional().describe("filter by page id (a singleton page has one entry)"),
     status: z.enum(["draft", "published"]).optional(),
+    externalKey: z.string().optional().describe(PARAM_TEXT.externalKeyFilter),
     where: z.record(z.string(), z.unknown()).optional().describe(PARAM_TEXT.where),
     sort: z.string().max(100).optional().describe(PARAM_TEXT.sort),
     page: z.number().int().min(1).optional().describe(PARAM_TEXT.page),
@@ -3456,7 +3493,7 @@ function buildToolDefs(deps) {
     metaDescription: clearableText(500),
     noindex: z.boolean().optional().describe("hide this entry from search engines and site search"),
     ...headPatchShape,
-    schemaType: z.enum(["WebPage", "AboutPage", "ContactPage", "CollectionPage", "Blog", "BlogPosting", "Article", "Product", "FAQPage", "Event", "Organization", "LocalBusiness"]).nullable().optional(),
+    schemaType: z.enum(SCHEMA_ORG_TYPES).nullable().optional(),
     schema: z.union([z.record(z.string(), z.unknown()), z.array(z.record(z.string(), z.unknown()))]).nullable().optional()
   });
   const updateEntryInput = z.object({
@@ -3587,6 +3624,17 @@ function buildToolDefs(deps) {
     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)"),
+    // Stored markers on a prop: nothing refuses a prop value for them. Declared so an echo keeps them.
+    readOnly: z.union([z.literal(true), z.literal("developer")]).optional(),
+    lockReason: z.string().max(200).optional(),
+    showIf: z.object({
+      match: z.enum(["all", "any"]),
+      rules: z.array(z.object({
+        field: z.string().min(1),
+        op: z.enum(["eq", "neq", "in", "isSet"]),
+        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."),
     // ⚠ 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.
@@ -3669,7 +3717,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."
+      "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)."
     )
   });
   const updateComponentInput = z.object({
@@ -3729,7 +3777,8 @@ function buildToolDefs(deps) {
         slug: z.string().min(1).optional().describe("a page slug, when one page has it; or pass `pageId`"),
         blockJson: z.array(blockObject).describe("REPLACES this page's whole block composition")
       })
-    ).min(1).max(50)
+    ).min(1).max(50),
+    dryRun: z.boolean().optional().describe(PARAM_TEXT.dryRun)
   });
   const listComponentsInput = z.object({
     detail: z.boolean().optional().describe("true = every component's full blockJson and props. Costly and rarely what you want \u2014 read one definition with get_component instead.")
@@ -3795,16 +3844,17 @@ function buildToolDefs(deps) {
       def(
         "update_media",
         "Update a media asset",
-        "Describe an existing media asset: set its alt text, caption, transcript or focal point (focalX/focalY, the spot crops keep in frame; delivered images carry it with width, height and thumbHash). 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.",
+        "Describe an existing media asset: set its alt text, caption, transcript, `decorative` (no alt text needed) or focal point (focalX/focalY, the spot crops keep in frame; delivered images carry it with width, height and thumbHash). 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."),
+          decorative: z.boolean().optional().describe("needs no alt text"),
           focalX: z.number().min(0).max(1).nullable().optional().describe(PARAM_TEXT.focalX),
           focalY: z.number().min(0).max(1).nullable().optional().describe(PARAM_TEXT.focalY)
         }).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, focalX: a.focalX, focalY: a.focalY }))
+        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, decorative: a.decorative, focalX: a.focalX, focalY: a.focalY }))
       ),
       def(
         "list_media",
@@ -3994,15 +4044,27 @@ ${d.outline}` : "Proposed Content structure.", d);
         "update_redirect",
         "Update a redirect",
         "Update an existing redirect in place \u2014 change where it points, its HTTP status, or disable it without deleting. Prefer this over delete+create: it keeps the redirect's id and preserves the chain-collapse rewrites of other rules pointing at it. Only provided fields change. Loops 422, duplicate sources 409.",
-        z.object({ redirectId: z.string().min(1).describe("redirect id (from list_redirects)"), sourcePath: z.string().min(1).optional(), destination: z.string().min(1).optional(), redirectType: z.enum(["301", "302", "307", "308"]).optional(), isActive: z.boolean().optional().describe("set false to disable without deleting") }).shape,
+        z.object({ redirectId: z.string().min(1).describe("redirect id (from list_redirects)"), sourcePath: z.string().min(1).optional(), destination: z.string().min(1).optional(), redirectType: z.enum(["301", "302", "307", "308", "410"]).optional().describe("HTTP status; 410 = Gone"), isActive: z.boolean().optional().describe("set false to disable without deleting") }).shape,
         async (c, a) => ok("Updated redirect.", await data(c, "PATCH", `/management/redirects/${s(a.redirectId)}`, { sourcePath: a.sourcePath, destination: a.destination, redirectType: a.redirectType, isActive: a.isActive }))
       ),
       def(
         "create_redirect",
         "Create a redirect",
         "Create a URL redirect \u2014 e.g. a 301 after renaming a page's slug. `sourcePath` is the path to redirect FROM ('/old-page'), `destination` the path/url TO ('/new-page'). Chains collapse; loops/dupes rejected. Defaults to 301.",
-        z.object({ sourcePath: z.string().min(1), destination: z.string().min(1), redirectType: z.enum(["301", "302", "307", "308"]).optional() }).shape,
-        async (c, a) => ok("Created redirect.", await data(c, "POST", `/management/redirects`, { sourcePath: a.sourcePath, destination: a.destination, redirectType: a.redirectType }))
+        z.object({ sourcePath: z.string().min(1), destination: z.string().min(1).optional(), redirectType: z.enum(["301", "302", "307", "308", "410"]).optional().describe("default '301'; 410 = Gone, omit destination"), dryRun: z.boolean().optional().describe("true = return the verdict, write nothing") }).shape,
+        async (c, a) => ok(a.dryRun === true ? "Dry run: nothing written." : "Created redirect.", await data(c, "POST", `/management/redirects`, { sourcePath: a.sourcePath, destination: a.destination, redirectType: a.redirectType, dryRun: a.dryRun }))
+      ),
+      def(
+        "import_redirects",
+        "Import redirects",
+        NEW_TOOL_TEXT.import_redirects,
+        z.object({
+          rows: z.array(z.record(z.string(), z.unknown())).optional().describe("[{ sourcePath, destination?, redirectType? }]"),
+          text: z.string().optional().describe("the file's contents, instead of rows"),
+          format: z.enum(["csv", "_redirects", "vercel"]).optional().describe("of `text` (default 'csv')"),
+          dryRun: z.boolean().optional().describe("default false")
+        }).shape,
+        async (c, a) => ok(a.dryRun === true ? "Dry run: nothing written." : "Imported redirects.", await data(c, "POST", `/management/redirects/import`, { rows: a.rows, text: a.text, format: a.format, dryRun: a.dryRun }))
       ),
       def(
         "delete_redirect",
@@ -4336,7 +4398,7 @@ ${d.outline}` : "Proposed Content structure.", d);
         "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,
-        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", "WebPage", "AboutPage", "ContactPage", "CollectionPage", "Blog", "BlogPosting", "Article", "Product", "FAQPage", "Event", "Organization", "LocalBusiness"]).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,
+        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(
             c.url(`/management/pages/${s(a.pageId)}/meta`),
@@ -4494,6 +4556,8 @@ ${res.warnings.join("\n")}` : summary, res.data);
           showIf: z.record(z.string(), z.unknown()).nullable().optional().describe("same shape as on add_field; null clears it"),
           ui: z.record(z.string(), z.unknown()).nullable().optional().describe("same vocabulary as on add_field; null clears it"),
           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),
           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"),
@@ -4604,10 +4668,11 @@ ${res.warnings.join("\n")}` : summary, res.data);
         NEW_TOOL_TEXT.create_content_entries,
         z.object({
           contentModelId: z.string().min(1).describe("the collection every entry belongs to (from list_content_models)"),
-          entries: z.array(z.object({ slug: z.string().optional(), data: z.record(z.string(), z.unknown()) })).min(1).max(200).describe("1-200 entries, each {slug?, data}")
+          entries: z.array(z.object({ slug: z.string().optional(), data: z.record(z.string(), z.unknown()), ...upsertShape })).min(1).max(200).describe("1-200 entries, each {slug?, data}"),
+          dryRun: z.boolean().optional().describe(PARAM_TEXT.dryRun)
         }).shape,
         // The whole body: the per-row receipt is `data`, the counts ride in `meta`.
-        async (c, a) => ok("Batch receipt.", await c.fetchJSON(c.url(`/management/content/entries/batch`), { method: "POST", body: JSON.stringify({ contentModelId: a.contentModelId, entries: a.entries }) }))
+        async (c, a) => ok(a.dryRun ? DRY_RUN_SUMMARY : "Batch receipt.", await c.fetchJSON(c.url(`/management/content/entries/batch`), { method: "POST", body: JSON.stringify({ contentModelId: a.contentModelId, entries: a.entries, dryRun: a.dryRun }) }))
       ),
       def(
         "translate_entry",
@@ -4800,7 +4865,7 @@ ${res.warnings.join("\n")}` : summary, res.data);
       def(
         "list_seo_issues",
         "List SEO issues",
-        "Scan every published page for SEO problems (missing or over-long titles and descriptions, missing OG image, noindex, absent schema) and return them with severities. Computed live \u2014 nothing is stored.",
+        "Scan every published page for SEO problems (missing or over-long titles and descriptions, missing OG image, noindex, invalid pasted schema) and return them with severities. Also reports accessibility issues as `a11y.*` codes with block ids. Computed live \u2014 nothing is stored.",
         z.object({}).shape,
         async (c) => ok("SEO issues.", await data(c, "GET", `/management/insights/seo-issues`))
       ),
@@ -5142,7 +5207,7 @@ ${notes.join("\n")}` : summary, created);
         async (args) => withClient(async (client) => {
           const modelDupes = duplicateKeys(flatFieldKeys(args.fields));
           if (modelDupes.length > 0) return fail(duplicateKeyFailure(modelDupes));
-          const model = await client.createModel({
+          const input = {
             name: args.name,
             slug: args.slug,
             ...args.description !== void 0 ? { description: args.description } : {},
@@ -5150,7 +5215,9 @@ ${notes.join("\n")}` : summary, created);
             ...args.kind !== void 0 ? { kind: args.kind } : {},
             ...args.fieldsets !== void 0 ? { fieldsets: dropProvenance(args.fieldsets) } : {},
             fields: toFields(args.fields)
-          });
+          };
+          if (args.dryRun) return dryRunOf(client, "POST", `/management/content/models`, input);
+          const model = await client.createModel(input);
           return ok(
             `Created content model '${model.name}' (${model.fields.length} field(s)).`,
             model
@@ -5168,6 +5235,15 @@ ${notes.join("\n")}` : summary, created);
       handler: guard(
         async (args) => withClient(async (client) => {
           if (!args.modelId === !args.pageId) return fail("Pass exactly one of modelId (a content model) or pageId (a page).");
+          if (args.dryRun) {
+            return dryRunOf(
+              client,
+              args.pageId ? "PATCH" : "POST",
+              args.pageId ? `/management/pages/${args.pageId}` : `/management/content/models/${args.modelId}/fields`,
+              { addFields: [toField(args)], ...args.after !== void 0 ? { after: args.after } : {} },
+              confirmedHeaders(args.confirmed)
+            );
+          }
           if (args.pageId) {
             const input2 = {
               // Cast: the SDK types `options` as string[], narrower than the API, which also takes
@@ -5224,19 +5300,23 @@ ${notes.join("\n")}` : summary, created);
       },
       handler: guard(
         async (args) => withClient(async (client) => {
-          const created = await client.createEntry({
+          const input = {
             contentModelId: args.contentModelId,
             ...args.slug !== void 0 ? { slug: args.slug } : {},
             ...args.data !== void 0 ? { data: args.data } : {},
             // The SDK's input type predates localization; its body is the input as given.
             ...args.locale !== void 0 ? { locale: args.locale } : {},
-            ...args.translationOf !== void 0 ? { translationOf: args.translationOf } : {}
-          });
+            ...args.translationOf !== void 0 ? { translationOf: args.translationOf } : {},
+            ...args.externalKey !== void 0 ? { externalKey: args.externalKey, source: args.source, runId: args.runId } : {}
+          };
+          if (args.dryRun) return dryRunOf(client, "POST", `/management/content/entries`, input);
+          const created = await client.createEntry(input);
           const published = args.status !== void 0 && args.status !== "draft" ? await client.updateEntry(created.id, { status: args.status }) : created;
           const { warnings, ...entry } = published;
           const notes = [.../* @__PURE__ */ new Set([...created.warnings ?? [], ...warnings ?? []])];
           return ok(
-            [`Created entry '${entry.slug}' (id ${entry.id}, status ${entry.status}).`, ...notes].join("\n"),
+            // With an external key the write may have updated the entry, or left it unchanged.
+            [`${args.externalKey ? "Stored" : "Created"} entry '${entry.slug}' (id ${entry.id}, status ${entry.status}).`, ...notes].join("\n"),
             entry
           );
         })
@@ -5299,7 +5379,7 @@ ${notes.join("\n")}` : summary, created);
       name: "update_content_entry",
       config: {
         title: "Update a content entry's values",
-        description: "Update a content entry's `data` (field values) and/or status by id. `data` is keyed by field key; a nested 'array' (zone) value is an object { nonRepeatable: {\u2026}, repeatable: [{\u2026}] }, a primitive 'array' is a plain list; an image value may carry this placement's focal {x,y} and crop {top,right,bottom,left} (0\u20131). Use this to edit an existing entry; for a singleton page prefer set_page_content. \u{1F534} `data` REPLACES the entry's whole value object: an optional field you leave out is DELETED, and a required one you leave out fails the whole write. To change one field, pass merge:true, or read the entry (get_content_entry), change that key and send the whole object back. " + ENTRY_META_NOTE,
+        description: "Update a content entry's `data` (field values) and/or status by id. `data` is keyed by field key; a nested 'array' (zone) value is an object { nonRepeatable: {\u2026}, repeatable: [{\u2026}] }, a primitive 'array' is a plain list; an image value may carry this placement's focal {x,y} and crop {top,right,bottom,left} (0\u20131). Use this to edit an existing entry; for a singleton page prefer set_page_content. \u{1F534} `data` REPLACES the entry's whole value object: an optional field you leave out is DELETED, and a required one you leave out fails the whole write. To change one field, pass merge:true, or read the entry (get_content_entry), change that key and send the whole object back. " + FIELD_LOCKED_NOTE + " " + ENTRY_META_NOTE,
         inputSchema: updateEntryInput.shape
       },
       handler: guard(
@@ -5678,14 +5758,17 @@ ${notes.join("\n")}` : summary, created);
             try {
               const written = await client.fetchJSON(
                 client.url(`/management/pages/${pageId}/meta`),
-                { method: "PATCH", body: JSON.stringify({ blockJson: page.blockJson }) }
+                { method: "PATCH", body: JSON.stringify({ blockJson: page.blockJson, ...args.dryRun ? { dryRun: true } : {} }) }
               );
-              results.push({ ok: true, 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 });
             } catch (err) {
               results.push({ ok: false, pageId, slug: page.slug, error: errorText(err) });
             }
           }
           const failed = results.filter((r) => !r.ok).length;
+          if (args.dryRun) {
+            return ok(DRY_RUN_SUMMARY, { dryRun: true, results, wouldCompose: results.length - failed, failed });
+          }
           return ok(
             `Composed ${results.length - failed} of ${args.pages.length} page(s)${failed ? `; ${failed} failed \u2014 see the per-item errors` : ""}. These are page DRAFTS: publish each with update_page status:'published'. Then call get_site_composition for the receipt.`,
             results
@@ -6801,13 +6884,13 @@ delivered value \u2014 they change editor chrome only.
 { "key": "testimonials", "label": "Testimonials", "type": "repeater",
   "ui": { "collapsed": true, "preview": { "title": "author", "media": "avatar" },
           "layout": "grid", "icon": "double-quote", "itemLabel": "Testimonial" },
-  "helpText": "Three to five. Shortest quotes read best.",
+  "helpText": "Three to five.",
   "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.
+- **\`helpText\`** \u2014 the exception: most fields need none. Write it only when the author needs it to
+  type the right value: a format or unit ("Price in cents."), a placement the canvas cannot show, a
+  real constraint, a fallback. Never restate the label ("The title field"), never coach ("Keep it short").
 - **\`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
@@ -7040,9 +7123,10 @@ Do not stop at the plan or at a partial receipt \u2014 finish the whole site, ne
 10. \`get_next_steps\`: if it lists \`upgrade-section-roots\` (section spacing and style handles), in the repo run
    \`npx @bettercms-ai/convert@latest --upgrade-sections --root . --dry-run\`, read the plan, then run it for real. For every
    root its receipt lists as \`skipped\`, pass the block down by hand: \`{...sectionRootAttrs(block)}\` on the section root, or
-   \`data-bcms-style=""\` plus \`style={...}\` from \`block.style\`. Run \`--verify-styles\` again and restore what it lists (the
-   marker and the inline style from \`block.style\` are allowed; changing a class or an existing style is not). Deploy,
-   poll, call \`get_next_steps\` again and tell me what it still lists. Not listed: say so and move on; invent no work.
+   \`data-bcms-style=""\` plus \`style={...}\` from \`block.style\`. For \`upgrade-element-styles\` (field width, spacing, text handles)
+   do the same with \`npx @bettercms-ai/convert@latest --upgrade-element-styles --root . --dry-run\`. Run \`--verify-styles\` again
+   and restore what it lists (the marker, and the inline style from \`block.style\` or \`fieldAttrs\`, are allowed; changing a class
+   or an existing style is not). Deploy, poll, call \`get_next_steps\` again, tell me what it still lists. Not listed: say so; invent no work.
 11. Ask me whether to commit and push to my repository, commit only, or leave it uncommitted (unpushed, the
    next rebuild from my repo drops it). Touch git only as I answer.`;
 var FIELD_UI_PROMPT = {
@@ -7155,8 +7239,9 @@ 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 }. 'select' needs
-   config.options; 'group'/'table' need config.fields; 'slot' holds ONE nested component;
+   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'
+   is ONE prop on a button block's 'props', never a label prop plus a url prop; 'slot' holds ONE nested component;
    '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
    them, and a second copy is a second source of truth that drifts on the first edit.