@bettercms-ai/mcp 0.68.2 → 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
@@ -7156,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.