@bettercms-ai/mcp 0.50.0 → 0.51.1

package/dist/index.js

@@ -16,6 +16,19 @@ import { z } from "zod";
 
 // ../types/src/component.ts
 var SECTION_DOCTRINE = "STRUCTURE (separate from schema): a page is composed of SECTIONS. NEVER build a page out of loose top-level heading/text/image/button/spacer blocks \u2014 they cannot be moved, duplicated or swapped as a unit, the visual editor cannot outline or name them, and every one of them becomes its own section in the editor. A hero of a headline, a lede and two CTAs is ONE section, not four. TWO SHAPES, and the choice is about REUSE. (1) A band that appears on more than one page, or that needs layout variants, is a COMPONENT with a `sectionType` \u2014 see create_component. Components sharing a `sectionType` are that section's VARIANTS (one Hero: 'Centered' for the home page and 'Two-column' for about, same prop keys so a swap keeps the content). This is also the only shape the editor's 'Add a section' picker can insert, and the only one that gets a family name and a variant switcher. (2) A genuinely one-off band on a single page is a `section` BLOCK whose `props.children` hold its blocks. THE TRADEOFF, stated in the present tense because it is real today: inside a component, ONLY the leaves a declared prop TARGETS are click-to-edit on the canvas \u2014 each declared prop's `target` is re-keyed to that PLACEMENT's own override address, so editing it changes this page and not the shared definition. A prop with no `target` still SHOWS as a dock control, but its override reaches no rendered slot, so editing it changes nothing on the page. Copy that no prop points at is worse still: no binding and no control, unreachable from click-to-edit AND from the dock, changeable only by editing the component definition, which rewrites every page that places it. A `section` block's children stay click-to-edit unconditionally. So when you choose a component, DECLARE A PROP \u2014 WITH A `target` \u2014 for every string, link and image a marketer will ever touch; a component with un-propped editable copy is the defect, not the component. In the dock an unset prop shows EMPTY and inherits the definition's default, so set props explicitly when you want the current copy visible there. Do not hand-write a band's JSON: start from a built-in section blueprint (list_components returns locked `builtin:*` blueprints with no projectId \u2014 hero-centered, hero-split, feature-grid-three, cta-banner and nine more), each already rooted in a `section` block with its editable leaves declared as props. INLINE its blockJson as a `section` block for a one-off band; for a recurring band, materialize the blueprint with create_component so it becomes project-scoped before implementation validation, Output or publication. Direct `builtin:*` component references exist only for legacy delivery compatibility. Two consecutive call-to-action buttons are two sibling `button` blocks inside the same section \u2014 never a `columns` block, which is a `repeat(N,1fr)` grid and would stretch each CTA to half the container. Buttons are inline-level and flow side by side on their own.";
+var COMPONENT_PROP_TYPES = [
+  "text",
+  "richtext",
+  "image",
+  "url",
+  "boolean",
+  "number",
+  "select",
+  "group",
+  "table",
+  "slot",
+  "form"
+];
 
 // ../types/src/layout-lucide-icons.ts
 var LAYOUT_SECTION_ICONS = Object.freeze([
@@ -2578,6 +2591,11 @@ function buildToolDefs(deps) {
       "the page's VISUAL composition \u2014 how a components-first page is built. Place one `component` block per section: {type:'component', id:'<stable>', props:{componentId:'<id from create_component>'}}. The component must be PUBLISHED (publish_component) or it renders as nothing on the live site. Independent of `fields`, which is a typed schema for a site's own code to read."
     ),
     fields: z.array(fieldObject).optional().describe("the page's typed schema fields"),
+    // Undeclared, this was stripped by the SDK before the request, so a singleton created with its
+    // values arrived without them. The remote adapter and POST /management/pages always took it.
+    data: z.record(z.string(), z.unknown()).optional().describe(
+      "a SINGLETON's field VALUES keyed by field key \u2014 seeds its entry in the same call. If any value is refused the page is still created, none of `data` is saved, and the result names ENTRY_SEED_FAILED with the per-field reasons: fix them and write with set_page_content."
+    ),
     metaTitle: z.string().optional().describe("SEO meta title"),
     metaDescription: z.string().optional().describe("SEO meta description")
   });
@@ -2730,7 +2748,12 @@ function buildToolDefs(deps) {
       max: z.number().optional().describe("'number' fields only \u2014 inclusive ceiling"),
       phoneFormat: z.enum(["any", "e164"]).optional().describe("'phone' fields only"),
       pattern: z.string().optional().describe("'text' / 'textarea' / 'url' fields only \u2014 a regex")
-    }).optional().describe("per-field rules the API enforces on submit; each key is only valid on the field types listed")
+    }).optional().describe("per-field rules the API enforces on submit; each key is only valid on the field types listed"),
+    ui: z.strictObject({
+      countryPicker: z.boolean().optional().describe("'phone' fields only \u2014 render a country picker; the value is stored as E.164"),
+      defaultCountry: z.string().optional().describe("'phone' fields only \u2014 uppercase ISO 3166-1 alpha-2 the picker starts on; requires countryPicker"),
+      showFlags: z.boolean().optional().describe("'phone' fields only \u2014 show the country flag beside the dial code; requires countryPicker")
+    }).optional().describe("per-field presentation options; each key is only valid on the field types listed")
   });
   const formSettingsShape = {
     description: z.string().optional(),
@@ -2761,10 +2784,12 @@ function buildToolDefs(deps) {
     key: z.string().min(1),
     label: z.string().min(1),
     target: z.object({ blockId: z.string().min(1), path: z.string().min(1) }),
-    // MUST stay at parity with componentPropDefSchema on the server. `update_component`
-    // REPLACES the whole `props` array, so a type this enum omits cannot be echoed back: an
-    // agent that reads a component and writes it back DESTROYS every prop of that type.
-    type: z.enum(["text", "richtext", "image", "url", "boolean", "number", "select", "group", "table", "slot"]),
+    // Parity with componentPropDefSchema is no longer a promise to keep by hand — both now read
+    // the SAME list from @bettercms-ai/types. It used to be a copy, and the failure that made
+    // was quiet and total: `update_component` REPLACES the whole `props` array, so a type this
+    // enum omitted could not be echoed back, and an agent reading a component and writing it
+    // straight back DESTROYED every prop of that type on a 200.
+    type: z.enum(COMPONENT_PROP_TYPES),
     // 'slot' holds ONE nested component instance; config.componentIds restricts what may
     // fill it. Absent here until now, so a slot allowlist was unreachable from stdio even
     // once the enum allowed the type.
@@ -3324,7 +3349,7 @@ ${d.outline}` : "Proposed Content structure.", d);
       def(
         "get_project",
         "Get the connected project",
-        "Get the connected project's info \u2014 id, name, slug, subdomain, and its live URL (https://<handle>.bettercms.site). Use it to tell the user where their site is published / link the result. " + BRAND_KIT_NOTE,
+        "Get the connected project's info \u2014 id, name, slug, subdomain, and its live URL (https://<handle>.bettercms.site). Use it to tell the user where their site is published / link the result. It also returns `useCdn` and `mediaBaseUrl` \u2014 the origin this project's media is minted and resized on. A deployed site's `PUBLIC_BCMS_MEDIA_URL` / `mediaUrl` must equal `mediaBaseUrl`, or resized images 404 on any rung but production. " + BRAND_KIT_NOTE,
         z.object({}).shape,
         async (c) => ok("Project.", await data(c, "GET", `/management/projects/current`))
       ),
@@ -3390,7 +3415,7 @@ ${d.outline}` : "Proposed Content structure.", d);
       def(
         "set_media_delivery",
         "Choose where this site's media is served from",
-        "Record whether this project's media (images, video, files) is served from the BetterCMS CDN or from the API origin. `useCdn: true` is the DEFAULT and the recommendation: URLs are minted on the CDN host, or on the project's own CDN base when it stores media in its own bucket (BYOK). `useCdn: false` mints them on the API origin instead \u2014 the same service serving the same bytes, only under a different hostname. ASK THE USER; do not pick for them. Called without `useCdn`, this tool asks them directly (or hands you the question to ask). \u{1F534} IT APPLIES TO URLs MINTED FROM NOW ON \u2014 new uploads, entry saves, get_media. It does NOT rewrite URLs already stored in published content, and it does not need to: the old URLs keep resolving. To move an existing image, re-save the field that holds it. \u{1F534} IT IS THE BACKEND HALF ONLY. A deployed frontend builds its own transform URLs with @bettercms-ai/image-url, which has its own media host \u2014 set `PUBLIC_BCMS_MEDIA_URL` (or the integration's `mediaUrl` option) to match, or that site's resized images stay on the CDN while everything else moves. Read the current answer from get_project (`useCdn`). Re-callable; the last answer wins.",
+        "Record whether this project's media (images, video, files) is served from the BetterCMS CDN or from the API origin. `useCdn: true` is the DEFAULT and the recommendation: URLs are minted on the CDN host, or on the project's own CDN base when it stores media in its own bucket (BYOK). `useCdn: false` mints them on the API origin instead \u2014 the same service serving the same bytes, only under a different hostname. ASK THE USER; do not pick for them. Called without `useCdn`, this tool asks them directly (or hands you the question to ask). \u{1F534} IT APPLIES TO URLs MINTED FROM NOW ON \u2014 new uploads, entry saves, get_media. It does NOT rewrite URLs already stored in published content, and it does not need to: the old URLs keep resolving. To move an existing image, re-save the field that holds it. \u{1F534} IT IS THE BACKEND HALF ONLY. A deployed frontend builds its own transform URLs with @bettercms-ai/image-url, which has its own media host \u2014 set `PUBLIC_BCMS_MEDIA_URL` (or the integration's `mediaUrl` option) to match, or that site's resized images stay on the CDN while everything else moves. Read the current answer from get_project: `useCdn` is the choice, `mediaBaseUrl` is the origin it produces \u2014 the value the frontend's `PUBLIC_BCMS_MEDIA_URL` must match. Re-callable; the last answer wins.",
         // Optional in the schema for the same reason `framework` and `preference` are: a
         // required arg is rejected by the SDK before the handler runs, which would kill the
         // elicitation below and leave the model guessing.
@@ -3440,7 +3465,7 @@ ${d.outline}` : "Proposed Content structure.", d);
       def(
         "list_content_models",
         "List content models",
-        "List the content models (reusable schemas for dynamic collections like Blog/Products) in the connected project.",
+        "List the content models (reusable schemas for dynamic collections like Blog/Products) in the connected project. A project-scoped connection sees its own project's models plus workspace-level ones, which it can read but not change.",
         z.object({}).shape,
         async (c) => ok("Content models.", await data(c, "GET", `/management/content/models`))
       ),
@@ -3477,7 +3502,7 @@ ${d.outline}` : "Proposed Content structure.", d);
       def(
         "update_page",
         "Edit a page",
-        "Edit a page: title, slug, SEO metaTitle/metaDescription, structured data (`schemaType`, `schema`), publish status (draft|published), and `blockJson` (its block composition \u2014 passing it REPLACES the whole array, so read get_page first). It does NOT change the field SCHEMA \u2014 use add_page_field / set_page_content for that. Renaming the slug keeps content intact. Publishing copies the draft blocks live in the same call. STRUCTURED DATA is native SEO, never a field: leave it out and the page gets Automatic JSON-LD from its content (WebSite on the home page, Blog/CollectionPage on a collection's list page, WebPage otherwise); `schemaType` picks an explicit schema.org type whose properties are filled from the content; `schema` is pasted JSON-LD and wins over both (null clears it). " + PAGE_HEAD_NOTE + " " + SECTION_DOCTRINE,
+        "Edit a page: title, slug, SEO metaTitle/metaDescription, structured data (`schemaType`, `schema`), publish status (draft|published), and `blockJson` (its block composition \u2014 passing it REPLACES the whole array, so read get_page first). 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_page_field / 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), 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() }).shape,
         async (c, a) => {
           const res = await c.fetchJSON(
@@ -3488,10 +3513,9 @@ ${d.outline}` : "Proposed Content structure.", d);
             }
           );
           const note = res.redirectNote;
-          return ok(
-            note ? `Updated page. An existing redirect from ${note.source} already points to ${note.existingDestination}; it wasn't changed, so the old address does not redirect to the new one.` : "Updated page.",
-            res.data
-          );
+          const summary = note ? `Updated page. An existing redirect from ${note.source} already points to ${note.existingDestination}; it wasn't changed, so the old address does not redirect to the new one.` : "Updated page.";
+          return ok(res.warnings?.length ? `${summary}
+${res.warnings.join("\n")}` : summary, res.data);
         }
       ),
       // ── Code + deploy (parity with remote /mcp; needs artifact:write) ──
@@ -3550,7 +3574,7 @@ ${d.outline}` : "Proposed Content structure.", d);
       def(
         "get_binding_report",
         "Check what on the live site is editable",
-        "The receipt for 'is this site actually EDITABLE?'. Every release scans the built HTML for the element that renders each CMS field value; this returns what that scan found, per slot: `mode` ('text-match' = bindings guessed from rendered text, 'declared' = the template declares them), `pagesInspected`, `bound` (elements carrying a binding), and `unmatched` \u2014 per page, each path with its kind and the reason it failed (not-declared / ambiguous-text / no-element). DEPLOY FIRST: before any release there is no report and this answers pages 0, mode null, refreshRequired true. It certifies exactly one thing \u2014 that every non-empty field of every page has SOME element carrying its path. It cannot see copy that was never modelled, so diff each route's visible text against its entry values yourself before calling a page done. `builtRoutes` lists the routes the live build has HTML for (null when unknown: runtime release, >500 routes, or a report older than this field). `canvas.lane` names the live-preview lane this build gives the editor \u2014 `bridge` (the build ships BcmsDraftBridge), `draft-route` (a node runtime rendering drafts server-side) or `none`, in which case get_next_steps carries the recipe (playbook section 11); null means the report predates the field. `unaddressable` counts visible text on the live site that no field owns \u2014 the one thing `unmatched` structurally cannot see, because it only ever speaks about fields that already exist. EVERY release measures it server-side on every inspected page: `{count, pages, measuredAt, routes:[{path, count, visible, buckets:[{tag, context, chars, nodes, samples}]}]}`, where `path` is the route (the empty string is the home page), `visible` its countable characters (ornaments, skip links and the platform badge excluded from both sides) and `buckets` where the unowned text is, biggest first. Anything over `count / visible > 0.02` is copy the CMS cannot see: fix it in the SOURCE (wrap the run in an element the codemod can bind, or declare `<BcmsField path=\u2026>`), deploy, re-read \u2014 playbook section 11 has the loop. An author turning the editor's Unbound text control on posts a bare count of text NODES for the route they opened (no `visible`, no buckets); those rows are reported only for a build the release never measured, never summed with the release's characters. `skipReasons` says why pages were not inspected (`no-html`, `route-cap`, `authored-content` = the singleton lane declined the project, so NO route of it has a page), and `coverage.error` = `nothing-bound` means not one element of this build carries a binding, so the percentage beside it describes a site this build is not. `unaddressable` is measured PER SLOT; on a promote-gated project pass slot:'current' to read the tree the editor frames. Pass `slot` ('current' or 'staging') to read the other tree; the default is the slot this project's releases land in.",
+        "The receipt for 'is this site actually EDITABLE?'. Every release scans the built HTML for the element that renders each CMS field value; this returns what that scan found, per slot: `mode` ('text-match' = bindings guessed from rendered text, 'declared' = the template declares them), `pagesInspected`, `bound` (elements carrying a binding), and `unmatched` \u2014 per page, each path with its kind and the reason it failed (not-declared / ambiguous-text / no-element). DEPLOY FIRST: before any release there is no report and this answers pages 0, mode null, refreshRequired true. `refreshReason` says which of two states that is: `never-generated` \u2014 no report was ever written for this slot, and only a release BetterCMS itself builds and serves writes one, so a HEADLESS site never gets one and redeploying the same way will not change it (verify that site by fetching it); `outdated` \u2014 a report exists in an older shape, and the next release rewrites it. It certifies exactly one thing \u2014 that every non-empty field of every page has SOME element carrying its path. It cannot see copy that was never modelled, so diff each route's visible text against its entry values yourself before calling a page done. `builtRoutes` lists the routes the live build has HTML for (null when unknown: runtime release, >500 routes, or a report older than this field). `canvas.lane` names the live-preview lane this build gives the editor \u2014 `bridge` (the build ships BcmsDraftBridge), `draft-route` (a node runtime rendering drafts server-side) or `none`, in which case get_next_steps carries the recipe (playbook section 11); null means the report predates the field. `unaddressable` counts visible text on the live site that no field owns \u2014 the one thing `unmatched` structurally cannot see, because it only ever speaks about fields that already exist. EVERY release measures it server-side on every inspected page: `{count, pages, measuredAt, routes:[{path, count, visible, buckets:[{tag, context, chars, nodes, samples}]}]}`, where `path` is the route (the empty string is the home page), `visible` its countable characters (ornaments, skip links and the platform badge excluded from both sides) and `buckets` where the unowned text is, biggest first. Anything over `count / visible > 0.02` is copy the CMS cannot see: fix it in the SOURCE (wrap the run in an element the codemod can bind, or declare `<BcmsField path=\u2026>`), deploy, re-read \u2014 playbook section 11 has the loop. An author turning the editor's Unbound text control on posts a bare count of text NODES for the route they opened (no `visible`, no buckets); those rows are reported only for a build the release never measured, never summed with the release's characters. `skipReasons` says why pages were not inspected (`no-html`, `route-cap`, `authored-content` = the singleton lane declined the project, so NO route of it has a page), and `coverage.error` = `nothing-bound` means not one element of this build carries a binding, so the percentage beside it describes a site this build is not. `unaddressable` is measured PER SLOT; on a promote-gated project pass slot:'current' to read the tree the editor frames. Pass `slot` ('current' or 'staging') to read the other tree; the default is the slot this project's releases land in.",
         z.object({ slot: z.enum(["current", "staging"]).optional().describe("which release tree to read; defaults to the one this project deploys to") }).shape,
         async (c, a) => ok("Binding report.", await data(c, "GET", `/management/projects/current/binding-report${q({ slot: a.slot })}`))
       ),
@@ -3588,7 +3612,7 @@ ${d.outline}` : "Proposed Content structure.", d);
       def(
         "componentize_sections",
         "Turn this site's derived sections into components",
-        "Turn this site's derived sections into components. CONFIRM WITH THE USER FIRST: show them get_componentize_plan's sections and say how many components it will create and which pages it will rewrite. It creates each proposed component as a DRAFT (its `sectionType` family, category 'section', placeable on any page) and replaces each page's DRAFT blocks with an ordered list of `component` instances \u2014 one per group, each carrying `props.bind: \"<groupKey>\"`, which points at the page field group that already holds the copy. So nothing is copied and nothing moves: the page keeps its `fields`, its values and its bindings, click-to-edit keeps working and the coverage meter does not change. Pass the plan's `digest`; a 409 `stale-plan` means the site changed since you read that plan, so read it again, show the user what changed and confirm again. Call it with `dryRun: true` first \u2014 same receipt, nothing written. Running it twice is safe: a group that already has a placement comes back in `sections.pending` as ALREADY_COMPONENTIZED and no second component is created. DRAFTS ONLY \u2014 an unpublished component renders as an EMPTY STRING on the live site, so publish_component each one and publish the pages before this reaches a visitor. Then run `npx @bettercms-ai/convert --componentize` in the repo so its templates render these sections from `pages[].blocks`. `copy` says WHO OWNS THE COPY. The default `bind` is the above: the words stay in the page's field group. `copy: \"instance\"` is the page-builder model \u2014 each placement takes that group's CURRENT draft values into its own `props.overrides` (a repeater becomes one table prop holding every row), records which page path each came from in `props.source`, and drops `props.bind`; the page's fields are KEPT and marked `origin: \"componentized\"`, so nothing is lost and the editor stops showing a second place to type the same words. Run it again and it converts nothing and duplicates nothing. `sections` narrows a run to named groupKeys (`hero`, `group-fast`); a key the plan does not list on the pages you named is refused as `unknown-section` rather than quietly doing nothing. Every component it CREATES is filed into a Component Group (the folders of the dashboard's Components tab): the one you name in `group` (found or created), else its section family \u2014 nav, header, footer or menu \u2192 Layout, an unnamed section \u2192 Sections, otherwise the family name (Hero, FAQ). A component it reuses keeps the Group it has; the receipt's `components.groups` lists the Groups it filed into.",
+        "Turn this site's derived sections into components. CONFIRM WITH THE USER FIRST: show them get_componentize_plan's sections and say how many components it will create and which pages it will rewrite. It creates each proposed component as a DRAFT (its `sectionType` family, category 'section', placeable on any page) and replaces each page's DRAFT blocks with an ordered list of `component` instances \u2014 one per group, each carrying `props.bind: \"<groupKey>\"`, which points at the page field group that already holds the copy. So nothing is copied and nothing moves: the page keeps its `fields`, its values and its bindings, click-to-edit keeps working and the coverage meter does not change. Pass the plan's `digest`; a 409 `stale-plan` means the site changed since you read that plan, so read it again, show the user what changed and confirm again. Call it with `dryRun: true` first \u2014 same receipt, nothing written. Read its `components.wouldDuplicate` before applying: each id is an existing component of the same family this run would sit a NEW one beside, because reuse is by identity and slug, never by family. Place those by hand or accept the second component knowingly. Running it twice is safe: a group that already has a placement comes back in `sections.pending` as ALREADY_COMPONENTIZED and no second component is created. DRAFTS ONLY \u2014 an unpublished component renders as an EMPTY STRING on the live site, so publish_component each one and publish the pages before this reaches a visitor. Then run `npx @bettercms-ai/convert --componentize` in the repo so its templates render these sections from `pages[].blocks`. `copy` says WHO OWNS THE COPY. The default `bind` is the above: the words stay in the page's field group. `copy: \"instance\"` is the page-builder model \u2014 each placement takes that group's CURRENT draft values into its own `props.overrides` (a repeater becomes one table prop holding every row), records which page path each came from in `props.source`, and drops `props.bind`; the page's fields are KEPT and marked `origin: \"componentized\"`, so nothing is lost and the editor stops showing a second place to type the same words. Run it again and it converts nothing and duplicates nothing. `sections` narrows a run to named groupKeys (`hero`, `group-fast`); a key the plan does not list on the pages you named is refused as `unknown-section` rather than quietly doing nothing. Every component it CREATES is filed into a Component Group (the folders of the dashboard's Components tab): the one you name in `group` (found or created), else its section family \u2014 nav, header, footer or menu \u2192 Layout, an unnamed section \u2192 Sections, otherwise the family name (Hero, FAQ). A component it reuses keeps the Group it has; the receipt's `components.groups` lists the Groups it filed into.",
         z.object({
           digest: z.string().min(1).describe("The `digest` get_componentize_plan returned. A different one is refused with 409 stale-plan."),
           pageIds: z.array(z.string().min(1)).optional().describe("Componentize only these pages (ids from the plan). Omit for every page the plan lists."),
@@ -3835,13 +3859,18 @@ ${d.outline}` : "Proposed Content structure.", d);
             // Cast: the SDK's ContentModelField types `options` as string[], narrower than the API,
             // which also takes {label, value} (backend selectFieldSchema).
             ...args.fields ? { fields: args.fields.map(toField) } : {},
+            ...args.data !== void 0 ? { data: args.data } : {},
             ...args.metaTitle !== void 0 ? { metaTitle: args.metaTitle } : {},
             ...args.metaDescription !== void 0 ? { metaDescription: args.metaDescription } : {}
           });
-          return ok(
-            `Created ${page.pageType ?? "page"} page '${page.title}' (id ${page.id}, slug ${page.slug}) with ${page.fields.length} field(s).`,
-            page
-          );
+          const { warnings, seedErrors, ...created } = page;
+          const summary = `Created ${created.pageType ?? "page"} page '${created.title}' (id ${created.id}, slug ${created.slug}) with ${created.fields.length} field(s).`;
+          const notes = [
+            ...warnings ?? [],
+            ...seedErrors ? Object.entries(seedErrors).map(([key, why]) => `  ${key}: ${why}`) : []
+          ];
+          return ok(notes.length ? `${summary}
+${notes.join("\n")}` : summary, created);
         })
       )
     },
@@ -3945,9 +3974,11 @@ ${d.outline}` : "Proposed Content structure.", d);
             ...args.slug !== void 0 ? { slug: args.slug } : {},
             ...args.data !== void 0 ? { data: args.data } : {}
           });
-          const entry = args.status !== void 0 && args.status !== "draft" ? await client.updateEntry(created.id, { status: args.status }) : created;
+          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}).`,
+            [`Created entry '${entry.slug}' (id ${entry.id}, status ${entry.status}).`, ...notes].join("\n"),
             entry
           );
         })
@@ -3977,7 +4008,7 @@ ${d.outline}` : "Proposed Content structure.", d);
       name: "list_content_entries",
       config: {
         title: "List content entries (incl. drafts)",
-        description: "List content entries \u2014 including drafts \u2014 filtered by model and/or page. Use it to SEE existing content before editing. For a singleton page, pass its pageId to get its single entry.",
+        description: "List content entries \u2014 including drafts \u2014 filtered by model and/or page. Use it to SEE existing content before editing. For a singleton page, pass its pageId to get its single entry. A project-scoped connection sees its own project's entries plus workspace-level ones, which it can read but not change.",
         inputSchema: listEntriesInput.shape
       },
       handler: guard(
@@ -4009,18 +4040,18 @@ ${d.outline}` : "Proposed Content structure.", d);
       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. Use this to edit an existing entry; for a singleton page prefer set_page_content. " + 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. 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, read the entry (get_content_entry), change that key, and send the whole object back. " + ENTRY_META_NOTE,
         inputSchema: updateEntryInput.shape
       },
       handler: guard(
         async (args) => withClient(async (client) => {
-          const entry = await client.updateEntry(args.entryId, {
+          const { warnings, ...entry } = await client.updateEntry(args.entryId, {
             ...args.data !== void 0 ? { data: args.data } : {},
             ...args.status !== void 0 ? { status: args.status } : {},
             ...args.slug !== void 0 ? { slug: args.slug } : {},
             ...args.meta !== void 0 ? { meta: args.meta } : {}
           });
-          return ok(`Updated entry '${entry.slug}' (id ${entry.id}, status ${entry.status}).`, entry);
+          return ok([`Updated entry '${entry.slug}' (id ${entry.id}, status ${entry.status}).`, ...warnings ?? []].join("\n"), entry);
         })
       )
     },
@@ -4327,7 +4358,7 @@ ${d.outline}` : "Proposed Content structure.", d);
       name: "publish_components",
       config: {
         title: "Publish many components in one call",
-        description: "Publish up to 100 components in ONE call \u2014 the same act as publish_component, once per item, copying each DRAFT definition to the live copy. Each item reports `{ ok, status, error, readiness }` and a failure never stops the run. \u{1F534} A 409 COMPONENT_IMPLEMENTATION_NOT_READY is NOT retried and must not be: it means this exact variant still needs passing implementation evidence and a HUMAN's approval in the BetterCMS dashboard, which no tool on this connection can grant and which has no bulk form. The item's `readiness` names what is missing \u2014 relay that to the user as the list of what only they can approve. 403 PUBLISH_NOT_GRANTED means this connection may author but not publish; 422 means the publish would break a Layout, and the item names which.",
+        description: "Publish up to 100 components in ONE call \u2014 the same act as publish_component, once per item, copying each DRAFT definition to the live copy. Each item reports `{ ok, status, error, readiness }` and a failure never stops the run. \u{1F534} A 409 COMPONENT_IMPLEMENTATION_NOT_READY is NOT retried and must not be: no tool on this connection can clear it, and it has no bulk form. It is never a component you just made with create_component in no variant group \u2014 that is dashboard-managed and publishes on the preflight alone. The refusal is for a REPO-managed component without exact validation evidence and a human's approval, or for a variant-group member (the provisioned navigation and footer) whose group's canonical-input contract is not published. Report its `readiness`. The item's `readiness` names what is missing \u2014 relay that to the user as the list of what only they can approve. 403 PUBLISH_NOT_GRANTED means this connection may author but not publish; 422 means the publish would break a Layout, and the item names which.",
         inputSchema: publishComponentsInput.shape
       },
       handler: guard(
@@ -4521,7 +4552,7 @@ ${lines.join("\n")}`, found);
       name: "publish_component",
       config: {
         title: "Publish a component",
-        description: "Publish one project-scoped component variant after its exact implementation evidence and human approval are ready: copy its DRAFT definition to the live copy and re-bake every published page that embeds it. This is the ONLY way a component reaches the live site. Built-in `builtin:*` rows are locked blueprints, not implementations; materialize one with create_component first. Workspace-global component publication is currently fail-closed. create_component and update_component write drafts, and an unpublished component renders as NOTHING live, with no error. Publish every component you place on a page. 403 PUBLISH_NOT_GRANTED means this connection may author but not publish: say so and let the user publish from the dashboard. \u{1F534} A 409 COMPONENT_IMPLEMENTATION_NOT_READY is NOT retried and must not be: this exact variant still needs passing implementation evidence and a HUMAN's approval in the BetterCMS dashboard, which no tool on this connection can grant. The response's `readiness` names what is missing \u2014 relay it to the user instead of retrying or routing around it. 422 means publishing would break a Layout that uses it \u2014 the response names which.",
+        description: "Publish one project-scoped component variant after its exact implementation evidence and human approval are ready: copy its DRAFT definition to the live copy and re-bake every published page that embeds it. This is the ONLY way a component reaches the live site. Built-in `builtin:*` rows are locked blueprints, not implementations; materialize one with create_component first. Workspace-global component publication is currently fail-closed. create_component and update_component write drafts, and an unpublished component renders as NOTHING live, with no error. Publish every component you place on a page. 403 PUBLISH_NOT_GRANTED means this connection may author but not publish: say so and let the user publish from the dashboard. \u{1F534} A 409 COMPONENT_IMPLEMENTATION_NOT_READY is NOT retried and must not be: no tool on this connection can clear it. It is never a component you just made with create_component in no variant group \u2014 that is dashboard-managed and publishes on the preflight alone. The refusal is for a REPO-managed component without exact validation evidence and a human's approval, or for a variant-group member (the provisioned navigation and footer) whose group's canonical-input contract is not published. Report its `readiness`. The response's `readiness` names what is missing \u2014 relay it to the user instead of retrying or routing around it. 422 means publishing would break a Layout that uses it \u2014 the response names which.",
         inputSchema: getComponentInput.shape
       },
       handler: guard(
@@ -5078,7 +5109,10 @@ axis: it is the picker TAB (hero / content / social-proof / conversion for secti
 footer for chrome; form; custom for page-specific).
 
 **4. Editor fields are \`props\`.** Types: \`text richtext image url boolean number select group
-table slot\`. Always set \`defaultValue\`. \`required\`, \`helpText\` and \`placeholder\` are editor
+table slot form\`. Always set \`defaultValue\`. \`form\` points at ONE Form document: target a
+\`form\` block's \`props\` and set \`defaultValue\` to \`{formId}\`. NEVER re-declare a form's fields
+as props \u2014 the Form document owns them, a second copy drifts on the first edit, and the Forms
+tab is where an author edits them. \`required\`, \`helpText\` and \`placeholder\` are editor
 hints the dashboard renders \u2014 they are NOT enforced at write time, so an override missing a
 required prop still saves; \`get_site_composition\` is what reports those. Use \`select\` with
 \`config.options\` for layout / theme / alignment / spacing variants that change only styling,
@@ -5284,7 +5318,7 @@ conversion is yours to write.
    \`{...bcms.home.hero.title}\` / \`{...bcms.blog.features.$(i)}\`. The hand form is
    \`data-bcms-field="<path>"\` (plus \`data-bcms-kind="richtext"|"image"\`), the \xA711 layout markers
    for nav and footer, and \`<div data-bcms-field="body" data-bcms-kind="document">\` around a
-   Portable Text render.
+   Portable Text render, whose per-block elements carry their own \`data-bcms-kind="richtext"\`.
    **A value that lives in an ATTRIBUTE \u2014 an \`href\`, an \`alt\`, an \`src\` \u2014 rides
    \`data-bcms-props\`, and its grammar is PIPES, NOT JSON:**
    \`data-bcms-props="<path>|<kind>|<domAttribute>"\`, semicolon-separated for several on one
@@ -5553,7 +5587,9 @@ Author a form (then the user embeds it with \`<BcmsForm form={getForm('Name')} /
    \`options\`), radio (needs \`options\`), number, phone, date, url, consent, hidden. Optional per
    field: required?, placeholder?, helpText? (shown under the input), defaultValue?,
    \`validation\` (\`emailPolicy\` on email, \`min\`/\`max\` on number, \`phoneFormat\` on phone,
-   \`pattern\` on text/textarea/url \u2014 a rule on any other type is a 400), and
+   \`pattern\` on text/textarea/url \u2014 a rule on any other type is a 400),
+   \`ui\` (\`countryPicker\` + \`defaultCountry\` on phone \u2014 renders a country picker and stores
+   E.164; \`defaultCountry\` without \`countryPicker\` is a 400), and
    \`showIf: { field, equals }\` for conditional display.
 3. **Settings** \u2014 name (used by getForm('Name')), submitLabel?, successMessage?, redirectUrl?.
 4. **Confirm**, then \`create_form\` { name, fields, ... } (returns the new id), or
@@ -5574,8 +5610,11 @@ 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 }. '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 }. 'select' needs
+   config.options; 'group'/'table' need config.fields; '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.
 5. **Confirm the structure** (AskUserQuestion: show the block tree), then \`create_component\`.
 6. **\`publish_component\`.** It lands as a DRAFT, and a draft component renders as NOTHING on
    the live site \u2014 no error, no placeholder. This step is not optional.