@bettercms-ai/mcp 0.49.0 → 0.50.0

package/dist/index.js

@@ -2410,7 +2410,11 @@ function toField(f) {
     ...f.config ? { config: f.config } : {}
   };
 }
-var STRUCTURE_NOTE = 'ORGANISATION ONLY: folders never change a URL, slug, content or publish state, and nothing is rebuilt or delivered. Folders nest at most 4 levels deep (a page or collection may sit in a level-4 folder). Icons are lucide icon names, e.g. "folder", "file-text", "rows-3", "house" (a-z, 0-9 and dashes); null clears one. SYSTEM FOLDERS (CPO-129): "home:pages" (Other pages), "home:collections" (Shared) and "home:globals" (Settings) always exist, even when the document has no record for them. They close the sidebar, below the folders you make, and can never be moved or deleted (400 NAV_SYSTEM_FOLDER), but rename_folder and set_icon work on them and create their record on first use. TYPE PURITY: anything inside Other pages, at any depth, must be a page, and anything inside Shared must be a collection, and Settings holds NO pages or collections at all, because globals are not sidebar items (subfolders under Settings are allowed but stay empty). Any of these is 400 NAV_TYPE_MISMATCH. Your own folders hold either kind. ACCESS (CPO-131): Requires Admin or Developer access to CHANGE the structure, the same access as editing the schema; anyone who can read content can call get_content_structure. A 403 SCHEMA_ACCESS_REQUIRED means the person behind this connection is not an Admin or Developer: stop and tell the user, do not retry. ROOT PINS (CPO-132): folderId \'root\' pins a page or collection at the top level; null returns it to its home (Other pages / Shared). Pins sit above the folders, in their own order, and may be pages or collections. In a document a pin is folderId "home:root", a virtual id with no folder record (a folder record with that id is 400 NAV_SYSTEM_FOLDER). KIND CHECK: an id is either a page or a collection, never both, and a custom folder holds either \u2014 so move_to_folder and set_icon VERIFY that the id really is the `kind` you named on this branch, and refuse a mismatch with 400 NAV_KIND_MISMATCH naming the kind to use; call it again with that kind, which also clears the wrong-kind entry. An id that resolves to nothing is allowed (it may exist on another branch) and the result says so. set_content_structure never refuses: it returns `warnings` and `kindMismatches`. get_content_structure marks such items `kindMismatch: true` and lists them in `summary.kindMismatches`. PAGE-BOUND MODELS (CPO-135): a page with fields has a content model bound to it. That model is NOT a collection \u2014 get_content_structure never lists it among collections or in the tree, and move_to_folder / set_icon / set_content_structure refuse it with 400 NAV_PAGE_BOUND_MODEL naming the owning page (\'This model belongs to the page "\u2026"; organise the page.\'). Organise the PAGE instead, by its page id. If a stored document still references one it appears in `summary.hiddenItems` with `boundToPageId`, and the next single write drops it.';
+var BRAND_KIT_NOTE = "`brandKit` is the project's brand kit, read-only: colors, typography, radius and any typeScale/spacing/elevation/motion. It is edited in the BetterCMS dashboard; style sections with their `style` tokens rather than copying its values into props.";
+var MODEL_IF_MATCH_NOTE = "optimisticVersion from get_content_model. When sent, the update applies only if the model is still at that version; a 409 means someone changed it since \u2014 read it again and re-apply, never retry blindly. Omitted, the last write wins.";
+var ENTRY_META_NOTE = "SEO is native: set this entry's metaTitle, metaDescription, noindex, canonical, og, twitter, schemaType or schema in `meta` (never as model fields). `meta` MERGES into what is stored: a key you leave out is kept, null or an empty string clears it.";
+var PAGE_HEAD_NOTE = "noindex, canonical, og and twitter set the page's head extras; each MERGES into what is stored (a key you leave out is kept, null or an empty string clears it).";
+var STRUCTURE_NOTE = 'ORGANISATION ONLY: Content sidebar folders never change a URL, slug, content or publish state, and nothing is rebuilt or delivered; URL folders (page folders) are set in the dashboard. Folders nest at most 4 levels deep (a page or collection may sit in a level-4 folder). Icons are lucide icon names, e.g. "folder", "file-text", "rows-3", "house" (a-z, 0-9 and dashes); null clears one. SYSTEM FOLDERS (CPO-129): "home:pages" (Other pages), "home:collections" (Shared) and "home:globals" (Settings) always exist, even when the document has no record for them. They close the sidebar, below the folders you make, and can never be moved or deleted (400 NAV_SYSTEM_FOLDER), but rename_folder and set_icon work on them and create their record on first use. TYPE PURITY: anything inside Other pages, at any depth, must be a page, and anything inside Shared must be a collection, and Settings holds NO pages or collections at all, because globals are not sidebar items (subfolders under Settings are allowed but stay empty). Any of these is 400 NAV_TYPE_MISMATCH. Your own folders hold either kind. ACCESS (CPO-131): Requires Admin or Developer access to CHANGE the structure, the same access as editing the schema; anyone who can read content can call get_content_structure. A 403 SCHEMA_ACCESS_REQUIRED means the person behind this connection is not an Admin or Developer: stop and tell the user, do not retry. ROOT PINS (CPO-132): folderId \'root\' pins a page or collection at the top level; null returns it to its home (Other pages / Shared). Pins sit above the folders, in their own order, and may be pages or collections. In a document a pin is folderId "home:root", a virtual id with no folder record (a folder record with that id is 400 NAV_SYSTEM_FOLDER). KIND CHECK: an id is either a page or a collection, never both, and a custom folder holds either \u2014 so move_to_folder and set_icon VERIFY that the id really is the `kind` you named on this branch, and refuse a mismatch with 400 NAV_KIND_MISMATCH naming the kind to use; call it again with that kind, which also clears the wrong-kind entry. An id that resolves to nothing is allowed (it may exist on another branch) and the result says so. set_content_structure never refuses: it returns `warnings` and `kindMismatches`. get_content_structure marks such items `kindMismatch: true` and lists them in `summary.kindMismatches`. PAGE-BOUND MODELS (CPO-135): a page with fields has a content model bound to it. That model is NOT a collection \u2014 get_content_structure never lists it among collections or in the tree, and move_to_folder / set_icon / set_content_structure refuse it with 400 NAV_PAGE_BOUND_MODEL naming the owning page (\'This model belongs to the page "\u2026"; organise the page.\'). Organise the PAGE instead, by its page id. If a stored document still references one it appears in `summary.hiddenItems` with `boundToPageId`, and the next single write drops it.';
 function structureResult(d) {
   const message = d?.message;
   return ok(typeof message === "string" ? message : "Updated the Content structure.", d);
@@ -2469,6 +2473,19 @@ function errorText(err) {
   }
   return err instanceof Error ? err.message : String(err);
 }
+function refusalDetail(err) {
+  const api = apiError(err);
+  if (!api) return "";
+  const body = api.body && typeof api.body === "object" ? api.body : {};
+  const code = api.bodyCode ?? (typeof body.error === "string" && /^[A-Z][A-Z0-9_]+$/.test(body.error) ? body.error : void 0);
+  const lines = [
+    code ? `code: ${code}` : "",
+    body.readiness !== void 0 ? `readiness: ${JSON.stringify(body.readiness)}` : "",
+    body.issues !== void 0 ? `issues: ${JSON.stringify(body.issues)}` : ""
+  ].filter(Boolean);
+  return lines.length ? `
+${lines.join("\n")}` : "";
+}
 function authPrompt(err) {
   const text = [
     "\u{1F510} BetterCMS authorization required \u2014 you're not signed in yet.",
@@ -2518,7 +2535,7 @@ function buildToolDefs(deps) {
           return authPrompt(err);
         }
         if (err instanceof BetterCMSError) {
-          return fail(`BetterCMS error (${err.status} ${err.code}): ${err.message}`);
+          return fail(`BetterCMS error (${err.status} ${err.code}): ${err.message}${refusalDetail(err)}`);
         }
         return fail(`Unexpected error: ${err instanceof Error ? err.message : String(err)}`);
       }
@@ -2646,11 +2663,26 @@ function buildToolDefs(deps) {
     pageId: z.string().optional().describe("filter by page id (a singleton page has one entry)"),
     status: z.enum(["draft", "published"]).optional()
   });
+  const clearableText = (max) => z.string().max(max).nullable().optional();
+  const headPatchShape = {
+    canonical: clearableText(2048).describe("canonical URL; null clears"),
+    og: z.object({ title: clearableText(255), description: clearableText(500), image: clearableText(2048), type: clearableText(50) }).nullable().optional().describe("Open Graph; each key merges, null clears that key"),
+    twitter: z.object({ card: clearableText(50), title: clearableText(255), description: clearableText(500), image: clearableText(2048) }).nullable().optional().describe("Twitter card; each key merges, null clears that key")
+  };
+  const entryMetaInput = z.object({
+    metaTitle: clearableText(255),
+    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(),
+    schema: z.union([z.record(z.string(), z.unknown()), z.array(z.record(z.string(), z.unknown()))]).nullable().optional()
+  });
   const updateEntryInput = z.object({
     entryId: z.string().min(1).describe("content entry id"),
     data: z.record(z.string(), z.unknown()).optional().describe("field values keyed by field key"),
     status: z.enum(["draft", "published"]).optional(),
-    slug: slug.optional()
+    slug: slug.optional(),
+    meta: entryMetaInput.optional().describe("the entry's native SEO; merges into what is stored")
   });
   const deletePageInput = z.object({
     pageId: z.string().min(1).describe("id of the page to delete (from list_pages)")
@@ -2704,7 +2736,15 @@ function buildToolDefs(deps) {
     description: z.string().optional(),
     submitLabel: z.string().optional().describe("submit button label (default 'Submit')"),
     successMessage: z.string().optional(),
-    redirectUrl: z.string().url().optional().describe("URL to redirect to on success")
+    redirectUrl: z.string().url().optional().describe("URL to redirect to on success"),
+    // Spam + delivery settings. Each MUST parse exactly like its key in the route's
+    // createFormSchema (this package cannot import it); src/__tests__/mcp/mcp-parity.test.ts
+    // checks the two agree. Never add turnstileSecretKey: a secret does not belong in an
+    // agent's context.
+    turnstileEnabled: z.boolean().optional().describe("require a Cloudflare Turnstile check on submit"),
+    honeypotField: z.string().max(100).nullable().optional().describe("name of a hidden honeypot input; a submission that fills it is marked spam. null clears"),
+    notifyEmails: z.array(z.string().email()).optional().describe("addresses emailed on each submission (REPLACES the list)"),
+    webhookUrl: z.string().url().nullable().optional().describe("absolute URL that receives each submission as a POST. null clears")
   };
   const createFormInput = z.object({
     name: z.string().min(1).describe("human form name (used by getForm('Name'))"),
@@ -3284,7 +3324,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.",
+        "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,
         z.object({}).shape,
         async (c) => ok("Project.", await data(c, "GET", `/management/projects/current`))
       ),
@@ -3415,9 +3455,16 @@ ${d.outline}` : "Proposed Content structure.", d);
         "update_content_model",
         "Update a content model's metadata",
         "Rename a content model, edit its description/slug/urlPattern, or set its `fieldsets`. Never touches `fields`: use add_field to extend the schema. Provide modelId plus what to change. `fieldsets` REPLACES the list (send null to drop them all); then put a field in one with add_field's `fieldsetId`. `urlPattern` is the collection's entry URL, e.g. '/blog/:slug' (null clears it). A slug already used in this project and branch is refused with 409 `slug_taken`.",
-        z.object({ modelId: z.string().min(1), name: z.string().optional(), slug: z.string().optional(), description: z.string().optional(), urlPattern: urlPatternArg, fieldsets: fieldsetsArg.nullable() }).shape,
+        z.object({ modelId: z.string().min(1), name: z.string().optional(), slug: z.string().optional(), description: z.string().optional(), urlPattern: urlPatternArg, fieldsets: fieldsetsArg.nullable(), ifMatch: z.number().int().min(0).optional().describe(MODEL_IF_MATCH_NOTE) }).shape,
         // `fields` is deliberately not sent: the PATCH replaces `fields` wholesale when present.
-        async (c, a) => ok("Updated content model.", await data(c, "PATCH", `/management/content/models/${s(a.modelId)}`, { name: a.name, slug: a.slug, description: a.description, urlPattern: a.urlPattern, fieldsets: a.fieldsets }))
+        async (c, a) => ok(
+          "Updated content model.",
+          (await c.fetchJSON(c.url(`/management/content/models/${s(a.modelId)}`), {
+            method: "PATCH",
+            body: JSON.stringify({ name: a.name, slug: a.slug, description: a.description, urlPattern: a.urlPattern, fieldsets: a.fieldsets }),
+            ...a.ifMatch !== void 0 ? { headers: { "if-match": `W/"${a.ifMatch}"` } } : {}
+          })).data
+        )
       ),
       def(
         "get_content_types",
@@ -3430,14 +3477,14 @@ ${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). " + SECTION_DOCTRINE,
-        z.object({ 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,
+        "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,
+        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(
             c.url(`/management/pages/${s(a.pageId)}/meta`),
             {
               method: "PATCH",
-              body: JSON.stringify({ title: a.title, slug: a.slug, blockJson: a.blockJson, metaTitle: a.metaTitle, metaDescription: a.metaDescription, schemaType: a.schemaType, schema: a.schema, status: a.status })
+              body: JSON.stringify({ title: a.title, slug: a.slug, blockJson: a.blockJson, metaTitle: a.metaTitle, metaDescription: a.metaDescription, schemaType: a.schemaType, schema: a.schema, status: a.status, noindex: a.noindex, canonical: a.canonical, og: a.og, twitter: a.twitter })
             }
           );
           const note = res.redirectNote;
@@ -3541,16 +3588,17 @@ ${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.",
+        "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.",
         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."),
           pages: z.array(z.string().min(1)).optional().describe("The same page filter under the name the dashboard uses. Unioned with pageIds; an EMPTY list is refused rather than treated as every page."),
           sections: z.array(z.string().min(1)).optional().describe("Act only on these section groupKeys (from the plan). Every other section on the page keeps the placement it already has."),
           copy: z.enum(["bind", "instance"]).optional().describe("Who owns each section's copy: 'bind' (default) leaves it in the page fields; 'instance' moves it onto the placement and marks those fields origin: componentized."),
-          dryRun: z.boolean().optional().describe("true = return the receipt without writing anything. Do this first.")
+          dryRun: z.boolean().optional().describe("true = return the receipt without writing anything. Do this first."),
+          group: z.string().min(1).max(100).optional().describe("File the components this run creates into this Component Group (by NAME; created when missing). Omit to file each under its section family.")
         }).shape,
-        async (c, a) => ok("Componentized the sections.", await data(c, "POST", `/management/projects/current/componentize`, { digest: a.digest, pageIds: a.pageIds, pages: a.pages, sections: a.sections, copy: a.copy, dryRun: a.dryRun }))
+        async (c, a) => ok("Componentized the sections.", await data(c, "POST", `/management/projects/current/componentize`, { digest: a.digest, pageIds: a.pageIds, pages: a.pages, sections: a.sections, copy: a.copy, dryRun: a.dryRun, group: a.group }))
       ),
       def(
         "get_analytics_overview",
@@ -3961,7 +4009,7 @@ ${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.",
+        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,
         inputSchema: updateEntryInput.shape
       },
       handler: guard(
@@ -3969,7 +4017,8 @@ ${d.outline}` : "Proposed Content structure.", d);
           const 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.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);
         })
@@ -4070,7 +4119,7 @@ ${d.outline}` : "Proposed Content structure.", d);
       name: "create_form",
       config: {
         title: "Create a form",
-        description: "Create a form (fields + settings) in the bound project. CONFIRM the fields with the user first. Returns the new form's id \u2014 then embed it with `<BcmsForm form={getForm('Name')} />` from @bettercms-ai/next. Field types: text,email,textarea,select(needs options),radio(needs options),checkboxes(needs options),checkbox,number,phone,date,url,consent,hidden.",
+        description: "Create a form in the connected project from a field schema. Confirm the fields with the user first. Field types: text, email, textarea, select (needs options), radio (needs options), checkboxes (needs options), checkbox, number, phone, date, url, consent, hidden. Returns the new form's id. It lands as a DRAFT; call publish_form before embedding (a draft form returns 403 on submit). Embed it with `<BcmsForm form={getForm('Name')} />` from @bettercms-ai/next.",
         inputSchema: createFormInput.shape
       },
       handler: guard(
@@ -4095,6 +4144,23 @@ ${d.outline}` : "Proposed Content structure.", d);
         })
       )
     },
+    {
+      name: "publish_form",
+      config: {
+        title: "Publish a form",
+        description: "Publish a form by id so it accepts submissions. create_form and update_form only ever write a DRAFT, and a draft form answers every submit with 403 \u2014 call this before embedding it with `<BcmsForm form={getForm('Name')} />`. It re-bakes the project's site; `meta.rebuildQueued` says whether a rebuild was actually queued (false for a project with no connected source). 403 PUBLISH_NOT_GRANTED means this connection may author but not publish: say so and let the user publish from the dashboard Forms tab. 404 means the form is not in this connection's project.",
+        inputSchema: getFormInput.shape
+      },
+      handler: guard(
+        async (args) => withClient(async (client) => {
+          const res = await client.fetchJSON(
+            client.url(`/management/forms/${args.formId}/publish`),
+            { method: "POST" }
+          );
+          return ok(`Published form '${res.data?.name ?? args.formId}'.`, res);
+        })
+      )
+    },
     // ── Project/page Layout (draft commands + Global Layout publish; page overrides publish with the page) ──
     {
       name: "get_layout",
@@ -4207,7 +4273,7 @@ ${d.outline}` : "Proposed Content structure.", d);
       name: "create_component",
       config: {
         title: "Create a reusable component",
-        description: "Create a reusable component from a blockJson tree. THIS IS ALSO HOW A PAGE GETS ITS SECTIONS: set `sectionType` (e.g. 'Hero') and the component becomes a placeable section, selectable in the editor's 'Add a section' picker. Components sharing a `sectionType` are its layout VARIANTS \u2014 one Hero with a 'Centered' and a 'Two-column' variant, same prop keys, so a swap keeps the content. CONFIRM the structure with the user first. blockJson is an array of blocks \u2014 the same set create_page accepts (heading, text/richtext, image, button, spacer, video, columns, section, slider, tabs, navbar, footer, form, component, collection), NOT a narrower one; `section` nests child blocks in props.children and `columns` in props.columns. `props` declares overridable fields. Returns the new id \u2014 render with `<BcmsBlocks>`. Always lands as a DRAFT: it is not on the live site until someone publishes it from the dashboard. " + SECTION_DOCTRINE,
+        description: "Create a reusable component from a blockJson tree. THIS IS ALSO HOW A PAGE GETS ITS SECTIONS: set `sectionType` (e.g. 'Hero') and the component becomes a placeable section, selectable in the editor's 'Add a section' picker. Components sharing a `sectionType` are its layout VARIANTS \u2014 one Hero with a 'Centered' and a 'Two-column' variant, same prop keys, so a swap keeps the content. CONFIRM the structure with the user first. blockJson is an array of blocks \u2014 the same set create_page accepts (heading, text/richtext, image, button, spacer, video, columns, section, slider, tabs, navbar, footer, form, component, collection), NOT a narrower one; `section` nests child blocks in props.children and `columns` in props.columns. `props` declares overridable fields. Returns the new id \u2014 render with `<BcmsBlocks>`. Always lands as a DRAFT \u2014 call publish_component to put it on the live site; until then it renders as NOTHING there, with no error. " + SECTION_DOCTRINE,
         inputSchema: createComponentInput.shape
       },
       handler: guard(
@@ -4385,7 +4451,7 @@ ${lines.join("\n")}`, found);
       name: "update_component",
       config: {
         title: "Update a reusable component",
-        description: "Update a component by id \u2014 blockJson, props, name, or category. Read get_component first. Passing `blockJson`/`props` REPLACES them. This writes the DRAFT: the change does NOT appear on the live site until someone publishes the component from the dashboard.",
+        description: "Update a component by id \u2014 blockJson, props, name, or category. Read get_component first. Passing `blockJson`/`props` REPLACES them. This writes the DRAFT: call publish_component to push the change live.",
         inputSchema: updateComponentInput.shape
       },
       handler: guard(
@@ -4455,7 +4521,7 @@ ${lines.join("\n")}`, found);
       name: "publish_component",
       config: {
         title: "Publish a component",
-        description: "Publish a component: 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 \u2014 create_component and update_component write drafts, and an unpublished component renders as NOTHING on the live site, 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. 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: 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.",
         inputSchema: getComponentInput.shape
       },
       handler: guard(
@@ -4487,7 +4553,7 @@ ${lines.join("\n")}`, found);
       name: "generate_seo_meta",
       config: {
         title: "Generate SEO metadata",
-        description: "Generate SEO metadata (metaTitle, metaDescription, keywords, optional JSON-LD) for a piece of content. Pass the page/entry content as `text`. Returns a suggestion to apply via update_page or the entry SEO fields.",
+        description: "Generate SEO metadata (metaTitle, metaDescription, keywords, optional JSON-LD) for a piece of content. Pass the page/entry content as `text`. Returns a suggestion: apply a page's with update_page (metaTitle, metaDescription, schemaType, schema) and an entry's with update_content_entry `meta`.",
         inputSchema: generateSeoMetaInput.shape
       },
       handler: guard(
@@ -4679,7 +4745,10 @@ Do not create \`seoTitle\`, \`metaTitle\`, \`metaDescription\`, \`ogImage\`, \`c
 \`noindex\` or an \`seo\` group on ANY model, page or component. Every one of those already
 exists on the platform:
 
-    per page / entry   metaTitle, metaDescription \u2014 set with update_page / update_content_entry
+    per page           metaTitle, metaDescription, schemaType, schema \u2014 set with update_page
+    per entry          metaTitle, metaDescription, noindex, canonical, og, twitter, schemaType,
+                       schema \u2014 set with update_content_entry \`meta\` (merges; null clears a key)
+    page head extras   noindex, canonical, og, twitter \u2014 set with update_page (merges; null clears)
     site-wide defaults get_seo / update_seo \u2014 { metaTitle, metaDescription, ogImage, twitterHandle }
     generated for you  generate_seo_meta
     audited for you    list_seo_issues
@@ -4726,6 +4795,9 @@ is interpolated per entry with \`{{fieldKey}}\` placeholders \u2014 \`{{title}}\
     2. collections  create_content_model
     3. components   create_component                     (they land as DRAFTS)
     4. publish      publish_component  <- every component you intend to place
+                    (409 COMPONENT_IMPLEMENTATION_NOT_READY: this exact variant still needs passing
+                    implementation evidence and a HUMAN's approval in the dashboard, which no tool
+                    can grant; relay the response's readiness to the user, never retry)
     5. pages        create_page with blockJson placing those components
     6. content      create_content_entry / set_page_content
     7. publish      update_page status:'published'
@@ -5197,9 +5269,11 @@ conversion is yours to write.
    \`create_content_entry\`). Prose goes in as Portable Text arrays (\`_type: "block"\`); never
    markup inside a \`text\` field.
    **Prose MIGRATED from another CMS needs one extra check.** Every block's \`_type\` must be one
-   this platform stores \u2014 \`block\`, or \`bcmsBlock\` carrying a \`schemaKey\` such as
-   \`builtin:table\` \u2014 and a foreign node (a Sanity-shaped \`{_type:"table", rows:[{cells}]}\` is
-   the one that has actually happened) is not merely unrendered: it has no component here, so it
+   this platform stores \u2014 \`block\`, \`table\` (\`{_type:"table", rows:[{_key, cells:[{_key,
+   content:[...blocks], header?}]}]}\`; Sanity's row of plain strings, \`rows:[{cells:["a","b"]}]\`,
+   is admitted too), \`bcmsCode\`, \`bcmsDivider\`, \`bcmsMention\`, or \`bcmsBlock\` carrying a
+   \`schemaKey\` \u2014 and a foreign node (a Sanity image, \`{_type:"image", asset:{_ref}}\`, for one)
+   is not merely unrendered: it has no component here, so it
    vanishes from the HTML every delivery surface reads while the stored value still looks whole.
    Verify each \`_type\` against the schema before you write, not after.
 5. Codemod the templates. Read each value from the CMS (\`@bettercms-ai/astro\` /
@@ -5346,7 +5420,7 @@ back each prop's stored \`ui\` or you delete it along with the prop.
 **THE RECEIPT \u2014 read it back.** There is no separate verification tool and no mode to flip.
 \`get_content_model\` (and \`get_page\` / \`get_component\`) return each field's \u2014 and each component
 prop's \u2014 stored \`ui\`, \`helpText\` and \`showIf\`. A prop that is ABSENT from that response was not
-stored, whatever the write returned \u2014 \xA712 rule 3, applied to this feature. Declare, then read
+stored, whatever the write returned \u2014 \xA711 RECEIPTS rule 3, applied to this feature. Declare, then read
 back, then say it works.
 
 **No \`order\` property. Ever.** A field's order IS its index in \`fields\`. To put a new field
@@ -5475,13 +5549,19 @@ Author a form (then the user embeds it with \`<BcmsForm form={getForm('Name')} /
 @bettercms-ai/next). Confirm the fields with the user BEFORE creating. Never guess fields.
 1. **Discover** \u2014 \`list_forms\` to see existing forms; \`get_form\` to read one before editing.
 2. **Collect fields (loop)** \u2014 for each: key (machine key for the value), label, type. Types:
-   text, email, textarea, select (needs \`options: string[]\`), checkbox, number, phone, date,
-   url, consent, hidden. Optional per field: required?, placeholder?, defaultValue?, and
+   text, email, textarea, select (needs \`options: string[]\`), checkbox, checkboxes (needs
+   \`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
    \`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
    \`update_form\` { formId, ... } to edit (passing \`fields\` REPLACES the array \u2014 include all).
-5. Offer to wire \`<BcmsForm>\` into the page/component where the user wants it.`;
+5. The form lands as a DRAFT, and a draft refuses every submission (403): call
+   \`publish_form\` { formId } (on 403 PUBLISH_NOT_GRANTED, tell the user to publish it in the
+   dashboard Forms tab), then offer to wire \`<BcmsForm>\` into the page/component where the
+   user wants it.`;
 var COMPONENT_FLOW = `### Component authoring \u2192 \`create_component\` / \`publish_component\`
 Author a reusable section. blockJson is the visual definition; authoring it blind is
 error-prone, so go slow and confirm. Never guess the layout.
@@ -5493,7 +5573,9 @@ error-prone, so go slow and confirm. Never guess the layout.
    "Add a section" picker. Components sharing a sectionType are swappable VARIANTS, so reuse
    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|slot }.
+   { 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.
 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.