@bettercms-ai/mcp 0.35.0 → 0.37.0

package/dist/index.js

@@ -2024,29 +2024,30 @@ async function askFramework(deps) {
 }
 var AUTHORING_CHOICES = ["components", "fields"];
 var AUTHORING_LABELS = {
-  components: "Components \u2014 reusable section components placed as blocks; editors add, reorder and swap sections without touching a schema. Best for marketing and landing sites",
-  fields: "Fields \u2014 a typed field schema per page. Best for blogs, catalogues and directories, where many rows share one shape"
+  components: "Components (recommended) \u2014 reusable section components placed as blocks; editors add, reorder and swap sections without touching a schema. Recommend it for every marketing, landing, agency or product site",
+  fields: "Fields \u2014 a typed field schema per page. Only for a blog, catalogue or directory where many rows share one shape; editors can change a page's copy but cannot add, reorder or swap its sections"
 };
 var AUTHORING_PROMPT = [
   "Ask the user which authoring architecture this site should use, then call set_authoring_preference again with their answer as `preference`:",
   ...AUTHORING_CHOICES.map((c, i) => `  ${i + 1}. ${c} \u2014 ${AUTHORING_LABELS[c]}`),
   "",
-  "Answering 'components' does not convert anything \u2014 there is no field-to-block converter. It means you author the sections yourself: create_component, then publish_component (an unpublished component renders as NOTHING on the live site), then set_page_content placing `component` blocks. Once a page has blocks, list_extraction_candidates and extract_component fold the repeats.",
+  "On a site whose pages were DERIVED at import, answering 'components' redoes nothing: after set_authoring_preference, get_componentize_plan proposes one component per section (it reads the PUBLISHED pages \u2014 no deploy needed to reach it), you confirm it with the user, then componentize_sections places them with `props.bind` (dry run first \u2014 they land as drafts and the page keeps its fields, values and bindings, so click-to-edit and the coverage meter are unchanged), then publish_component each one, publish the pages, run `npx @bettercms-ai/convert --componentize` in the repo, and deploy. For a section group the plan lists as NO_GROUP_ROOT or NOT_A_SECTION there is nothing to componentize, so author that section with create_component and set_page_content.",
   "",
+  "Recommend components unless the user says the site is schema-first.",
   "Do not choose on their behalf. This is asked once per project."
 ].join("\n");
 async function askAuthoring(deps) {
   if (!deps.elicit) return { prompt: AUTHORING_PROMPT };
   try {
     const res = await deps.elicit({
-      message: "Which authoring architecture should this site use?",
+      message: "Which authoring architecture should this site use? Components is recommended for a marketing site.",
       requestedSchema: {
         type: "object",
         properties: {
           preference: {
             type: "string",
             title: "Authoring architecture",
-            description: "How this site's pages are composed. Asked once per project.",
+            description: "How this site's pages are composed. Components is recommended unless this is a schema-first site (a blog, catalogue or directory). Asked once per project.",
             enum: [...AUTHORING_CHOICES],
             enumNames: AUTHORING_CHOICES.map((c) => AUTHORING_LABELS[c])
           }
@@ -2208,6 +2209,49 @@ function ok(summary, data) {
 function fail(message) {
   return { content: [{ type: "text", text: message }], isError: true };
 }
+function componentIdsIn(blocks) {
+  const out = [];
+  const walk = (value) => {
+    if (!Array.isArray(value)) return;
+    for (const candidate of value) {
+      if (!candidate || typeof candidate !== "object") continue;
+      const block = candidate;
+      const props = block.props ?? {};
+      if (block.type === "component" && typeof props.componentId === "string" && props.componentId) {
+        out.push(props.componentId);
+      }
+      if (block.type === "section") walk(props.children);
+      else if (block.type === "columns" && Array.isArray(props.columns)) for (const column of props.columns) walk(column);
+      else if (block.type === "slider" && Array.isArray(props.slides)) {
+        for (const slide of props.slides) walk(slide?.children);
+      } else if (block.type === "tabs" && Array.isArray(props.tabs)) {
+        for (const tab of props.tabs) walk(tab?.children);
+      }
+    }
+  };
+  walk(blocks);
+  return out;
+}
+function apiError(err) {
+  if (!err || typeof err !== "object") return null;
+  const e = err;
+  if (typeof e.status !== "number") return null;
+  return {
+    status: e.status,
+    message: typeof e.message === "string" ? e.message : "",
+    bodyCode: typeof e.bodyCode === "string" ? e.bodyCode : void 0,
+    fieldErrors: e.fieldErrors && typeof e.fieldErrors === "object" ? e.fieldErrors : void 0,
+    body: e.body
+  };
+}
+function errorText(err) {
+  const api = apiError(err);
+  if (api) {
+    const fields = api.fieldErrors ? Object.entries(api.fieldErrors).map(([k, v]) => `${k}: ${v}`).join("; ") : "";
+    return `${api.status}${api.bodyCode ? ` ${api.bodyCode}` : ""} \u2014 ${fields || api.message}`;
+  }
+  return err instanceof Error ? err.message : String(err);
+}
 function authPrompt(err) {
   const text = [
     "\u{1F510} BetterCMS authorization required \u2014 you're not signed in yet.",
@@ -2460,7 +2504,13 @@ function buildToolDefs(deps) {
       max: z.number().optional(),
       step: z.number().optional()
     }).passthrough().optional(),
-    defaultValue: z.unknown().optional()
+    defaultValue: z.unknown().optional(),
+    // Editor hints, stored in the props JSON. `required` is NOT enforced at write time — an
+    // override that omits it still saves — so it is a marker the dashboard renders and
+    // get_site_composition counts, never a refusal. Parity: componentPropDefSchema on the server.
+    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)")
   });
   const getLayoutInput = z.object({
     scope: z.enum(["global", "page"]).default("global"),
@@ -2496,8 +2546,12 @@ function buildToolDefs(deps) {
     scope: z.enum(["global", "page"]).default("global"),
     pageId: z.string().min(1).optional(),
     projectId: z.string().min(1).optional().describe("required only for a workspace-scoped grant"),
-    command: layoutCommand.describe("one canonical discriminated Layout command; authority is derived from type"),
-    ifMatch: z.number().int().nonnegative().describe("revision returned by get_layout")
+    command: layoutCommand.optional().describe("one canonical discriminated Layout command; authority is derived from type"),
+    // Chrome is many commands — add a section, add a component to it, bind its fields — and each
+    // one needs the revision the PREVIOUS one returned. An agent doing that by hand runs
+    // get_layout between every write, and a single missed re-read is a 409 mid-sequence.
+    commands: z.array(layoutCommand).min(1).max(50).optional().describe("apply these commands IN ORDER, each against the revision the previous one returned. Mutually exclusive with `command`. Stops at the first failure and reports what was applied."),
+    ifMatch: z.number().int().nonnegative().describe("revision returned by get_layout. With `commands`, this is the revision for the FIRST command only \u2014 the rest are chained.")
   });
   const publishLayoutInput = z.object({
     projectId: z.string().min(1).optional().describe("required only for a workspace-scoped grant"),
@@ -2525,6 +2579,7 @@ function buildToolDefs(deps) {
     name: z.string().min(1),
     slug: slug.describe("url-safe unique slug (lowercase letters/numbers/hyphens)"),
     category: componentCategory.optional().describe("defaults to 'custom'"),
+    group: z.string().min(1).max(100).optional().describe("the folder editors see in the dashboard's Components tab, addressed by NAME (e.g. 'Sections', 'Navigation', 'Forms'). Resolved against this project's Groups and CREATED when missing, so a whole-site run can file everything without looking any id up first. Separate from `category`, which is the picker tab."),
     sectionType: sectionType.optional(),
     projectId: z.string().nullable().optional().describe("owning project id; null creates a workspace-wide global component"),
     allowedOn: allowedOn.optional(),
@@ -2536,6 +2591,7 @@ function buildToolDefs(deps) {
     componentId: z.string().min(1).describe("component id (from list_components)"),
     name: z.string().optional(),
     category: componentCategory.optional(),
+    group: z.string().min(1).max(100).optional().describe("move it into this Group (by NAME; created when missing) \u2014 the folder editors see in the dashboard's Components tab"),
     sectionType: sectionType.nullable().optional().describe(
       "null demotes it to an ordinary component \u2014 it disappears from the 'Add a section' picker, and instances already placed keep rendering but lose their section chrome and variant switcher"
     ),
@@ -2547,6 +2603,24 @@ function buildToolDefs(deps) {
   const getComponentInput = z.object({
     componentId: z.string().min(1).describe("component id (from list_components)")
   });
+  const createComponentsInput = z.object({
+    components: z.array(createComponentInput).min(1).max(50).describe("up to 50 components, each exactly the create_component input")
+  });
+  const publishComponentsInput = z.object({
+    componentIds: z.array(z.string().min(1)).min(1).max(100).describe("component ids (from list_components)")
+  });
+  const composePagesInput = z.object({
+    pages: z.array(
+      z.object({
+        pageId: z.string().min(1).optional().describe("page id (from list_pages); or pass `slug`"),
+        slug: z.string().min(1).optional().describe("page slug, resolved against list_pages; or pass `pageId`"),
+        blockJson: z.array(blockObject).describe("REPLACES this page's whole block composition")
+      })
+    ).min(1).max(50)
+  });
+  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.")
+  });
   const listExtractionCandidatesInput = z.object({
     projectId: z.string().min(1).optional().describe("only needed for a workspace-wide key")
   });
@@ -2877,7 +2951,7 @@ function buildToolDefs(deps) {
       def(
         "set_authoring_preference",
         "Set the site's authoring architecture",
-        "Record which authoring architecture this site uses \u2014 'components' (reusable section components placed as blocks; editors add, reorder and swap sections without touching a schema \u2014 best for marketing and landing sites) or 'fields' (a typed field schema per page \u2014 best for blogs, catalogues and directories). ASK THE USER; do not pick for them. Called without `preference`, this tool asks them directly (or hands you the question to ask). deploy_project, deploy_from_upload and promote_project all refuse with 409 AUTHORING_DECISION_REQUIRED until it is set, and that refusal carries this project's real page counts to show the user. Answering 'components' does NOT convert anything \u2014 there is no field-to-block converter; it means you author the sections yourself: create_component, then publish_component (an unpublished component renders as NOTHING on the live site), then set_page_content placing `component` blocks. Asked once per project; re-callable if the user changes their mind.",
+        "Record which authoring architecture this site uses \u2014 'components' (RECOMMENDED: reusable section components placed as blocks; editors add, reorder and swap sections without touching a schema \u2014 recommend it for every marketing, landing, agency or product site) or 'fields' (a typed field schema per page \u2014 only for a blog, catalogue or directory where many rows share one shape). ASK THE USER; do not pick for them. Called without `preference`, this tool asks them directly (or hands you the question to ask). deploy_project, deploy_from_upload and promote_project all refuse with 409 AUTHORING_DECISION_REQUIRED until it is set, and that refusal carries this project's real page counts to show the user. On a site whose pages were DERIVED at import, answering 'components' redoes nothing: after set_authoring_preference, get_componentize_plan proposes one component per section (it reads the PUBLISHED pages \u2014 no deploy needed to reach it), you confirm it with the user, then componentize_sections places them with `props.bind` (dry run first \u2014 they land as drafts and the page keeps its fields, values and bindings, so click-to-edit and the coverage meter are unchanged), then publish_component each one, publish the pages, run `npx @bettercms-ai/convert --componentize` in the repo, and deploy. Recommend components unless the user says the site is schema-first. Asked once per project; re-callable if the user changes their mind.",
         // Optional in the schema for exactly the reason `framework` is above: a required arg is
         // rejected by the SDK before the handler runs, which would kill the elicitation below
         // and leave the model guessing. Optional here, answered by a human there. The backend
@@ -3045,6 +3119,13 @@ function buildToolDefs(deps) {
         z.object({}).shape,
         async (c) => ok("Approved conversion plan.", await data(c, "GET", `/management/projects/current/conversion-plan`))
       ),
+      def(
+        "get_site_composition",
+        "Check every page is assembled from registered components",
+        "The receipt for 'is every page assembled from registered components?' \u2014 read-only, computed live, nothing is written. Call it at the START of a whole-site componentize run (playbook \xA712) for the before picture, and at the END as the proof. Per page: `kind` ('blocks' | 'fields-only' | 'empty'), a block census, `nonComponentBlocks` (loose TOP-LEVEL bands the editor's section lane cannot outline), and every `component` placement with the component's `status` ('published' | 'draft' | 'missing' \u2014 a draft renders as an EMPTY STRING on the live site), whether it is `inPicker` (a component with no sectionType is dropped from 'Add a section'), and any `emptyRequiredProps` \u2014 `required` is an editor hint the write path does not enforce, so this read is the only thing that reports it. Site-wide: `components` counts published/draft, `awaitingEvidence` and `awaitingApproval` (evidence is exact and a HUMAN must approve it in the BetterCMS dashboard \u2014 no tool here can grant that, and there is no bulk approve), plus `notInPicker` and `unused` ids; `layout.placements` is the chrome placed in the Global Layout draft. `verdict.everyPageComposed` with `verdict.reasons` is the answer to give the user. Pages are read DRAFT-inclusive, so a page composed but not yet published still shows its placements \u2014 check each page's own `status` before claiming the site is live.",
+        z.object({}).shape,
+        async (c) => ok("Site composition.", await data(c, "GET", `/management/projects/current/composition`))
+      ),
       def(
         "get_componentize_plan",
         "Get the plan for turning this site's sections into components",
@@ -3601,13 +3682,39 @@ function buildToolDefs(deps) {
     {
       name: "update_layout",
       config: {
-        title: "Apply one Layout draft command",
-        description: "Apply one permission-shaped values/composition/schema command to the Global Layout or a page override. Draft-only: this never publishes. Pass the revision from get_layout as ifMatch.",
+        title: "Apply Layout draft commands",
+        description: "Apply permission-shaped values/composition/schema commands to the Global Layout or a page override. Draft-only: this never publishes. Pass the revision from get_layout as ifMatch. ONE command in `command`, or an ordered batch in `commands` (prefer the batch for more than three of anything \u2014 placing site chrome is add-section, add-component and set-bindings in sequence): each command is applied against the revision the previous one RETURNED, so you do not re-read get_layout between them. A batch stops at the first failure and tells you how many were applied and the revision it stopped at \u2014 the earlier ones stand, because a Layout command is not a transaction.",
         inputSchema: commandLayoutInput.shape
       },
       handler: guard(async (args) => withClient(async (client) => {
-        const layout = await client.commandManagedLayout({ ...args, command: args.command });
-        return ok(`Updated ${layout.scope === "global" ? "Global" : `Page ${layout.pageSlug}`} Layout draft to revision ${layout.revision}.`, layout);
+        const queued = args.commands ?? (args.command ? [args.command] : []);
+        if (queued.length === 0) return fail("Pass `command` (one) or `commands` (an ordered batch).");
+        if (args.commands && args.command) return fail("Pass `command` or `commands`, not both \u2014 the order of the two would be undefined.");
+        let revision = args.ifMatch;
+        let layout;
+        const applied = [];
+        for (const command of queued) {
+          try {
+            layout = await client.commandManagedLayout({
+              scope: args.scope,
+              pageId: args.pageId,
+              projectId: args.projectId,
+              command,
+              ifMatch: revision
+            });
+          } catch (err) {
+            return fail(
+              `Layout command ${applied.length + 1} of ${queued.length} (${command.type}) failed: ${errorText(err)}. ${applied.length} command(s) were applied and remain in the draft; the Layout is at revision ${revision}. Re-read get_layout and continue from command ${applied.length + 1}.`
+            );
+          }
+          revision = layout.revision;
+          applied.push({ type: command.type, revision });
+        }
+        const where = layout.scope === "global" ? "Global" : `Page ${layout.pageSlug}`;
+        return ok(
+          `Applied ${applied.length} command(s) to the ${where} Layout draft; now at revision ${revision}.`,
+          { applied, revision, layout }
+        );
       }))
     },
     {
@@ -3627,15 +3734,28 @@ function buildToolDefs(deps) {
       name: "list_components",
       config: {
         title: "List reusable components",
-        description: "List the reusable components in the bound project \u2014 each with id, name, slug, category, blockJson, and props. Use it to find a component to render with `<BcmsBlocks>` from @bettercms-ai/next.",
-        inputSchema: {}
+        description: "List the reusable components in the bound project. By DEFAULT this is the catalogue: id, name, slug, category, `sectionType` (the section family \u2014 a component with none is not in the editor's 'Add a section' picker), `status` ('draft' renders as NOTHING on the live site), and the `group` an editor browses it under, plus the locked `builtin:*` blueprints. It deliberately does NOT carry block trees: the full list carries every component's draft AND live `blockJson`, which is the largest response this API produces, and one component's definition is what `get_component` is for. Pass `detail: true` for the old full shape when you genuinely need every definition at once (rendering with `<BcmsBlocks>` from @bettercms-ai/next).",
+        inputSchema: listComponentsInput.shape
       },
       handler: guard(
-        async () => withClient(async (client) => {
-          const list = await client.listComponents();
+        async (args) => withClient(async (client) => {
+          if (args.detail) {
+            const list2 = await client.listComponents();
+            return ok(`${list2.length} component(s) in the bound project (full definitions).`, list2);
+          }
+          const list = await client.listComponents({ select: "summary" });
           return ok(
             `${list.length} component(s) in the bound project.`,
-            list.map((cmp) => ({ id: cmp.id, name: cmp.name, slug: cmp.slug, category: cmp.category }))
+            list.map((cmp) => ({
+              id: cmp.id,
+              name: cmp.name,
+              slug: cmp.slug,
+              category: cmp.category,
+              sectionType: cmp.sectionType,
+              status: cmp.status,
+              group: cmp.groupName,
+              ...cmp.builtin ? { builtin: true } : {}
+            }))
           );
         })
       )
@@ -3668,6 +3788,132 @@ function buildToolDefs(deps) {
         })
       )
     },
+    /**
+     * ── The batch three ──────────────────────────────────────────────────────
+     *
+     * Sequential SDK calls with PER-ITEM receipts, and no new server route: the throughput
+     * problem is one round trip per component, not one query per component, and inventing a bulk
+     * endpoint would duplicate every validation, warning and governance gate the single writes
+     * already run. A whole-site componentize run is forty creates, a dozen page compositions and
+     * forty publishes; as individual tool calls that is a hundred turns of an agent's context
+     * spent on plumbing.
+     *
+     * 🔴 NOTHING STOPS THE RUN. A batch that aborts on item 31 has already written 30 rows that
+     * no receipt mentions, and the agent's only safe move is to re-run it and duplicate them.
+     * Every item reports its own outcome instead, and the summary line says how many failed.
+     */
+    {
+      name: "create_components",
+      config: {
+        title: "Create many components in one call",
+        description: "Create up to 50 components in ONE call \u2014 the same input as create_component, once per item. Prefer it over create_component whenever you are making more than three: a whole-site componentize run (playbook \xA712) is dozens, and one call each spends the turn on plumbing. Each item reports its own `{ ok, id, slug, error }`: a failure does NOT stop the run and the successful rows stay, so read the receipt and retry only the failures (a 409 on `slug` means that name is taken \u2014 change it, do not re-run the batch). Every component lands as a DRAFT, exactly as create_component does \u2014 it renders as NOTHING on the live site until it is published, which needs the owner's approval in the dashboard. Pass `group` on each item to file it into the folder editors browse. " + SECTION_DOCTRINE,
+        inputSchema: createComponentsInput.shape
+      },
+      handler: guard(
+        async (args) => withClient(async (client) => {
+          const results = [];
+          for (const input of args.components) {
+            try {
+              const cmp = await client.createComponent(input);
+              results.push({ ok: true, slug: cmp.slug, id: cmp.id, name: cmp.name });
+            } catch (err) {
+              results.push({ ok: false, slug: input.slug, error: errorText(err) });
+            }
+          }
+          const failed = results.filter((r) => !r.ok).length;
+          return ok(
+            `Created ${results.length - failed} of ${args.components.length} component(s)${failed ? `; ${failed} failed \u2014 see the per-item errors` : ""}. All are DRAFTS: publish_components once the owner has approved them, or they render as empty strings.`,
+            results
+          );
+        })
+      )
+    },
+    {
+      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.",
+        inputSchema: publishComponentsInput.shape
+      },
+      handler: guard(
+        async (args) => withClient(async (client) => {
+          const results = [];
+          for (const componentId of args.componentIds) {
+            try {
+              const res = await client.fetchJSON(
+                client.url(`/management/components/${componentId}/publish`),
+                { method: "POST" }
+              );
+              results.push({ ok: true, componentId, slug: res.data?.slug, status: res.data?.status ?? "published" });
+            } catch (err) {
+              const readiness = apiError(err)?.body?.readiness;
+              results.push({
+                ok: false,
+                componentId,
+                error: errorText(err),
+                ...readiness ? { readiness } : {}
+              });
+            }
+          }
+          const failed = results.filter((r) => !r.ok).length;
+          return ok(
+            `Published ${results.length - failed} of ${args.componentIds.length} component(s)${failed ? `; ${failed} could not be published \u2014 read each item's error and readiness, and tell the user which ones need THEIR approval in the dashboard` : ""}.`,
+            results
+          );
+        })
+      )
+    },
+    {
+      name: "compose_pages",
+      config: {
+        title: "Set many pages' block composition in one call",
+        description: "Give up to 50 pages their block composition in ONE call \u2014 the same write as update_page's `blockJson`, once per item, and it REPLACES each page's whole block array. Address a page by `pageId` or by `slug`. Each item reports `{ ok, pageId, slug, error }` and a failure does not stop the run. BEFORE writing anything it reads this project's component catalogue once and REFUSES any item placing a componentId the project does not have \u2014 that page would render the missing sections as empty strings with no error anywhere, which is the single hardest failure on this platform to trace back. Writes DRAFTS: publish each page with update_page status:'published' afterwards. " + SECTION_DOCTRINE,
+        inputSchema: composePagesInput.shape
+      },
+      handler: guard(
+        async (args) => withClient(async (client) => {
+          const needsSlug = args.pages.some((p) => !p.pageId);
+          const [known, pageList] = await Promise.all([
+            client.listComponents({ select: "summary" }),
+            needsSlug ? client.listPages() : Promise.resolve([])
+          ]);
+          const ids = new Set(known.map((c) => c.id));
+          const bySlug = new Map(pageList.map((p) => [p.slug, p.id]));
+          const results = [];
+          for (const page of args.pages) {
+            const pageId = page.pageId ?? (page.slug ? bySlug.get(page.slug) : void 0);
+            if (!pageId) {
+              results.push({ ok: false, slug: page.slug, error: `No page with slug '${page.slug}' in this project \u2014 pass a pageId from list_pages.` });
+              continue;
+            }
+            const unknown = [...new Set(componentIdsIn(page.blockJson))].filter((id) => !ids.has(id));
+            if (unknown.length) {
+              results.push({
+                ok: false,
+                pageId,
+                slug: page.slug,
+                error: `Refused: this page places component id(s) this project does not have \u2014 ${unknown.join(", ")}. A missing component renders as an empty string with no error, so nothing was written for this page.`
+              });
+              continue;
+            }
+            try {
+              const written = await client.fetchJSON(
+                client.url(`/management/pages/${pageId}/meta`),
+                { method: "PATCH", body: JSON.stringify({ blockJson: page.blockJson }) }
+              );
+              results.push({ ok: true, pageId, slug: written.data?.slug ?? page.slug, 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;
+          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
+          );
+        })
+      )
+    },
     {
       name: "list_extraction_candidates",
       config: {
@@ -3804,7 +4050,8 @@ touching a schema. This is what \`create_component\` + \`create_page(blockJson)\
 A collection (\`create_content_model\`) plus entries.
 
 Most real sites are both: components for the marketing pages, a collection for the blog.
-Decide before your first call; converting later means rewriting content.
+Decide before your first call; converting later means rewriting content \u2014 unless the site was
+DERIVED at import, where the componentize lane in \xA710 reuses every field.
 
 ## 2. The decision tree
 
@@ -3844,6 +4091,10 @@ Then declare what an editor may change, via \`props\`:
       { key: "ctaHref",  label: "CTA link", target: { blockId: "cta", path: "props.href" }, type: "url" }
     ]
 
+Each prop also takes \`required\`, \`helpText\` (\u2264 200 chars) and \`placeholder\` (\u2264 120), which the
+dashboard's prop editor renders. They are HINTS: nothing on the write path refuses a placement
+that leaves a required prop empty, so \`get_site_composition\` is what reports one.
+
 \u{1F534} **On a components-first page, \`props\` is the ONLY editing surface.** Click-to-edit binds
 \`heading\`/\`text\`/\`button\`/\`image\` blocks; it does **not** bind a \`component\` block, because
 a component's blocks belong to the shared definition, not to the instance. So a page built
@@ -3992,31 +4243,49 @@ out, let the user pick, call \`set_authoring_preference\`, then deploy again.
 It exists because an imported site arrives **field-driven whether anyone chose that or not**
 \u2014 a crawl-based import (Webflow, a starter, a template) emits pages with a typed field schema
 and an empty block tree, because that is all a crawl can infer. Nobody decided it. On a
-marketing site it is the wrong answer, and \xA71 already says why converting later means
-rewriting content. So the platform stops once, at the last moment it is still cheap.
-
-**Answering \`components\` does not convert anything.** There is no field-to-block converter,
-and \`extract_component\` cannot stand in for one: it scans \`blockJson\`, which is empty on
-exactly the pages that would need converting. What it means is that you author the sections,
-in this order:
-
-    1. create_component      per section (they land as DRAFTS)
-    2. publish_component     each one \u2014 unpublished renders as NOTHING, on a page that 200s
-    2b. publish_layout       if you authored site chrome \u2014 the layout is a separate publish
-    3. set_page_content      place them as \`component\` blocks on the page
-    4. list_extraction_candidates / extract_component
-                             now that blocks exist, fold any section repeated 3+ times
-
-Step 2 is not a formality: \`componentize_sections\` and \`create_component\` both land components
+marketing site it is the wrong answer. So the platform stops once, at the last moment it is
+still cheap \u2014 and on a derived site that moment costs nothing, because the componentize lane
+below reuses every field the import already derived.
+
+**Recommend \`components\`.** On a site whose pages were DERIVED at import \u2014 the site \xA713
+describes \u2014 it redoes nothing: the componentize lane turns each top-level field GROUP into a
+component placement, and the page keeps its fields, its values and its bindings. In this order:
+
+    1. set_authoring_preference { preference: "components" }
+    2. get_componentize_plan    one component per section, computed live; creates nothing. It
+                                reads this project's PUBLISHED pages, so no deploy is needed
+                                to reach it \u2014 the deploy is the last step, not the first
+    3. show the user the plan and CONFIRM \u2014 it says how many components and which pages
+    4. componentize_sections    \`dryRun: true\` first, then for real; components land as DRAFTS
+                                and each placement carries \`props.bind\` to the page's field
+                                group, so click-to-edit and the coverage meter do not change
+    5. publish_component        each one \u2014 unpublished renders as NOTHING, on a page that 200s
+    5b. publish_layout          if you authored site chrome \u2014 the layout is a separate publish
+    6. publish the pages
+    7. npx @bettercms-ai/convert --componentize   in the repo, so its templates render these
+                                sections from \`pages[].blocks\`
+    8. deploy                   the ONLY deploy this sequence needs
+
+Step 5 is not a formality: \`componentize_sections\` and \`create_component\` both land components
 as DRAFTS, so \`publish_component\` each one and publish the page \u2014 otherwise the canvas keeps
 painting the PUBLISHED copy and the editor reports N components unpublished.
 
-**Answering \`fields\` is a real answer, not a deferral.** A blog, a catalogue or a directory
-is schema-first by design (\xA71) and should stay that way. Say so and move on.
+**A site with nothing to componentize you author by hand.** Where the plan offers nothing for
+a group (\`NO_GROUP_ROOT\` \u2014 the page's field keys are still the derive lane's own;
+\`NOT_A_SECTION\` \u2014 a lone scalar with no family), and on a site with no derived pages at all,
+the order is \`create_component\` per section \u2192 \`publish_component\` each \u2192 \`set_page_content\`
+placing \`component\` blocks \u2192 \`list_extraction_candidates\` / \`extract_component\` to fold any
+section repeated 3+ times. \`extract_component\` is not a converter and cannot stand in for the
+componentize lane: it scans \`blockJson\`, which is empty on exactly the pages that would need
+converting.
+
+**Answering \`fields\` is a real answer, not a deferral** \u2014 for a SCHEMA-FIRST site. A blog, a
+catalogue or a directory is schema-first by design (\xA71) and should stay that way. On anything
+else it costs the editor the ability to add, reorder or swap sections. Say so and move on.
 
-Either way: ask, do not choose. The 409 carries this project's actual page counts \u2014 how many
-are field-driven, block-driven, and how many place a reusable component \u2014 so quote those to
-the user rather than describing the choice in the abstract.
+Either way: ask, do not choose \u2014 recommending is not answering. The 409 carries this project's
+actual page counts \u2014 how many are field-driven, block-driven, and how many place a reusable
+component \u2014 so quote those to the user rather than describing the choice in the abstract.
 
 ## 11. The canvas: what makes an imported site EDITABLE
 
@@ -4123,7 +4392,7 @@ your own server) has NO canvas today: the SDK's draft mode with \`stega: true\`
 per-field provenance in fetched strings, which prepares the content for editing surfaces, but do
 not promise a canvas for an externally-hosted site.
 
-**\xA712 \u2014 RECEIPTS: a claim about published state needs a read of the PUBLISHED copy.** The
+**RECEIPTS: a claim about published state needs a read of the PUBLISHED copy.** The
 doctrine this encodes cost a real incident (FLO-1188): a publish was verified against the
 draft for ~50 minutes because the reader silently returned the draft, and every check was
 green on the wrong document. Three rules, none optional:
@@ -4140,6 +4409,85 @@ green on the wrong document. Three rules, none optional:
        call's behavior doesn't change when you change a param, treat the param as dead and
        verify through an independent channel before trusting any result built on it.
 
+## 12. Componentize the entire website
+
+The whole-site ask \u2014 "turn every section into a reusable component, organised for editors" \u2014
+mapped onto what this platform actually models. Work the order at the end; each numbered part
+below is one heading of that ask.
+
+**1. Global elements.** Navbar, mobile nav, header and footer are the LAYOUT, not page content:
+\`get_layout\` then \`update_layout\`, and a chrome COMPONENT is placed into a Layout section with
+the \`add-component\` command. CTA buttons are \`button\` BLOCKS inside the section that uses them,
+exposed as \`text\` + \`url\` props \u2014 variant, size and icon are that block's own props and
+\`style\`, never a standalone Button component. Rich text is a \`richtext\` prop over a
+\`richtext\`/\`text\` block. Forms are \`create_form\` plus a \`form\` block, and form FIELDS are the
+one place the platform models \`required\`, \`placeholder\`, \`helpText\` and real \`validation\`
+(emailPolicy, min/max, phoneFormat, pattern) \u2014 put a site's validated inputs there. Cards,
+badges, tags, links, lists and media are BLOCKS inside a section, exposed through props; a
+repeatable row of them is ONE \`table\` prop whose \`config.fields\` describe the row. Accordions
+and FAQs: start from the \`builtin:faq-list\` blueprint, or use a \`tabs\` block. NOT MODELLED \u2014
+cookie banners, modals, breadcrumbs and pagination have no primitive at all. Leave them in the
+site's code and say so in your final summary.
+
+**2. One component per distinct section, one-offs included.** \`create_component\` with a
+\`sectionType\` IS the section. \`sectionType\` is the FAMILY (Hero, Features, Testimonials,
+Pricing, FAQ, Contact, Newsletter, CTA, Stats, Logo cloud, Content\u2026) and components sharing one
+are its VARIANTS \u2014 give a family the same prop KEYS or a swap drops content. A one-off band
+still gets its own component: its own family, plus \`allowedOn: ["slug:<page>"]\`. A component
+with NO \`sectionType\` never appears in the editor's "Add a section" picker. Start from the
+builtin blueprints \`list_components\` returns (\`builtin:*\`) instead of hand-writing block JSON.
+On a DERIVED site run \`get_componentize_plan\` \u2192 \`componentize_sections\` FIRST \u2014 it does most
+of this in one call.
+
+**3. The hierarchy editors see is the GROUP.** \`create_component\` and \`update_component\` take
+\`group\`: a NAME, resolved against the project's component groups and created when missing. That
+is the folder the dashboard's Components tab shows. Use the names the request asks for \u2014 Global,
+Navigation, Actions, Content, Forms, Media, Sections, Page-specific. \`category\` is a different
+axis: it is the picker TAB (hero / content / social-proof / conversion for sections; navbar /
+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
+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,
+and a SEPARATE variant component when the markup differs. Repeatable list \u2192 \`table\`; fixed
+cluster \u2192 \`group\`. Nesting is capped at TWO levels from the prop (a \`table\` row may hold a
+\`table\`, and that inner row is scalars only). Flatten anything deeper.
+
+**5. Design, responsiveness and accessibility.** \`componentize_sections\` and \`npx
+@bettercms-ai/convert --componentize\` move the section's markup VERBATIM \u2014 classes, responsive
+utilities, aria attributes and alt text all survive. Never restyle while componentizing. Run
+\`componentize_sections { dryRun: true }\` and the codemod's \`--dry-run\` first.
+
+**6. The final validation is \`get_site_composition\`.** It is the receipt for "is every page
+assembled from registered components?": per page its blocks and every component placement with
+that component's status, plus site totals \u2014 unpublished, awaiting evidence, awaiting approval,
+missing from the picker, placed nowhere \u2014 and \`verdict.everyPageComposed\` with the reasons it
+is false. A component reaches a visitor only once PUBLISHED, and publishing needs the project
+owner's approval in the DASHBOARD: evidence goes \`submit_section_manifest\` \u2192
+\`submit_section_validation\`, the owner approves there, then \`publish_components\`. There is no
+bulk approve, and no tool here can grant that approval. Finish with \`get_next_steps\`.
+
+**Order of operations.**
+
+    1.  get_site_composition        the before picture
+    2.  get_componentize_plan       DERIVED site only \u2014 confirm it with the user
+    3.  componentize_sections       dryRun first, then for real
+    4.  create_components           everything the plan did not cover, ONE call, each with a group
+    5.  compose_pages               every page's blockJson, ONE call
+    6.  update_layout { commands }  nav/footer chrome + add-component, ONE call
+    7.  evidence                    submit_section_manifest -> submit_section_validation
+    8.  owner approves in the dashboard, then publish_components   ONE call, per-item receipts
+    9.  update_page status:'published', publish_layout
+    10. get_site_composition, then get_next_steps
+
+**What to tell the user at the end.** The group hierarchy and what landed in each; every family
+and its variants; what you left in the site's code because the platform does not model it
+(cookie banners, modals, breadcrumbs, pagination) and why; and exactly which components are
+still waiting for THEIR approval in the dashboard \u2014 until that happens those sections render as
+an empty string on the live site.
+
 ## 13. Convert an imported repo into a CMS-backed, editable site
 
 \xA711 says a deploy does not make a site editable. This is the recipe that does, and it ends in a
@@ -4319,7 +4667,7 @@ conversion is yours to write.
    \`bound > 0\`, and \u2014 for a site converted against a pinned brief \u2014 \`coverage.pending: []\`. That certifies one thing only \u2014 that every non-empty field 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 you call the page done. Then publish, and
-   fetch the live URL cache-busted (\xA712: publish and deploy are separate claims).
+   fetch the live URL cache-busted (RECEIPTS in \xA711: publish and deploy are separate claims).
    \`get_next_steps\` keeps reporting the gap until every one of these holds.
 
 **Done means.** Whichever recipe you ran: \`get_binding_report\` reads \`mode "declared"\`,
@@ -4405,6 +4753,41 @@ error-prone, so go slow and confirm. Never guess the layout.
 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.
 `;
+var COMPONENTIZE_SITE_FLOW = `### Componentize the entire website \u2192 playbook \xA712 + the batch tools
+Read \`bettercms://playbook/schema\` \xA712 first \u2014 this is the short form of it.
+1. **Global elements.** Navbar / mobile nav / header / footer are the LAYOUT (\`get_layout\`,
+   \`update_layout\`; a chrome component is placed with the \`add-component\` command). CTA buttons
+   are \`button\` BLOCKS inside the section that uses them, exposed as \`text\` + \`url\` props \u2014
+   variant/size/icon are that block's own props and \`style\`, never a Button component. Rich text
+   is a \`richtext\` prop. Forms are \`create_form\` + a \`form\` block, and form FIELDS are the only
+   place with real \`required\` / \`placeholder\` / \`helpText\` / \`validation\`. Cards, badges, tags,
+   links, lists and media are blocks inside a section, repeatables as one \`table\` prop.
+   Accordions/FAQ: \`builtin:faq-list\` or a \`tabs\` block. NOT MODELLED: cookie banners, modals,
+   breadcrumbs, pagination \u2014 leave them in the site's code and say so at the end.
+2. **One component per distinct section**, one-offs included. \`sectionType\` is the family;
+   components sharing one are VARIANTS and must share prop KEYS. A one-off gets its own family
+   plus \`allowedOn: ["slug:<page>"]\`. Start from the \`builtin:*\` blueprints in
+   \`list_components\`. On a DERIVED site run \`get_componentize_plan\` \u2192 \`componentize_sections\`
+   first (dryRun first, and confirm the plan with the user).
+3. **Hierarchy** = \`group\` on create_component/update_component (a NAME; created when missing).
+   Use Global, Navigation, Actions, Content, Forms, Media, Sections, Page-specific. \`category\`
+   is the separate picker TAB.
+4. **Fields** = \`props\`: text, richtext, image, url, boolean, number, select, group, table, slot.
+   Always a \`defaultValue\`; \`required\` / \`helpText\` / \`placeholder\` are editor hints, not write
+   -time enforcement. \`select\` for styling-only variants, a separate component when the markup
+   differs. Nesting is capped at two levels \u2014 flatten anything deeper.
+5. **Quality.** The componentize lane and \`npx @bettercms-ai/convert --componentize\` move markup
+   VERBATIM \u2014 classes, responsive utilities, aria attributes, alt text all survive. Never
+   restyle. Dry-run first.
+6. **Validation** = \`get_site_composition\`: every page's placements, each component's status,
+   and \`verdict.everyPageComposed\` with its reasons. Publishing needs the OWNER's approval in
+   the dashboard (evidence via \`submit_section_manifest\` \u2192 \`submit_section_validation\`), then
+   \`publish_components\`. No tool here can grant that approval, and there is no bulk approve.
+
+**Order:** get_site_composition \u2192 (get_componentize_plan \u2192 componentize_sections) \u2192
+create_components \u2192 compose_pages \u2192 update_layout { commands } \u2192 evidence + owner approval \u2192
+publish_components \u2192 publish the pages / publish_layout \u2192 get_site_composition \u2192 get_next_steps.
+Prefer the batch tools whenever there is more than three of anything.`;
 var LAYOUT_FLOW = `### Project/page Layout authoring \u2192 \`get_layout\` / \`update_layout\` / \`publish_layout\`
 Edit the project's draft Global Layout or one page's draft override. \`update_layout\` never
 changes the live site; \`publish_layout\` takes the Global Layout draft live (page overrides go
@@ -4491,6 +4874,8 @@ ${FORM_FLOW}
 
 ${COMPONENT_FLOW}
 
+${COMPONENTIZE_SITE_FLOW}
+
 ${LAYOUT_FLOW}
 
 ${BUILD_SITE_FLOW}
@@ -4642,6 +5027,36 @@ On 409 slug_taken, offer an alternative slug; on 401/403, the MCP key needs (re)
       ]
     })
   );
+  server.registerPrompt(
+    "componentize_site",
+    {
+      title: "Componentize the entire website (guided)",
+      description: "Turn every section of a site into a reusable component, organised into groups editors can browse: audit with get_site_composition, create the components in one call, compose every page, then publish what the owner has approved.",
+      argsSchema: {
+        request: z2.string().optional().describe("scope or emphasis, e.g. 'marketing pages only'")
+      }
+    },
+    ({ request }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Componentize this entire website in BetterCMS.${request ? ` Scope: "${request}".` : ""}
+
+${COMPONENTIZE_SITE_FLOW}
+
+${STRUCTURE_RULE}
+
+Confirm the component library with the user before creating it. End with the summary \xA712 asks
+for: the group hierarchy, each family and its variants, what you left in the site's code because
+the platform does not model it, and which components are still waiting for the owner's approval
+in the dashboard \u2014 those render as an empty string until they are published.`
+          }
+        }
+      ]
+    })
+  );
   server.registerPrompt(
     "build_site",
     {
@@ -4784,7 +5199,7 @@ function buildServer(deps) {
       // 🔴 The plain-language ask, routed — the stdio twin of the hosted connector's line
       // (src/routes/mcp/index.ts MCP_INSTRUCTIONS). "Make my site editable" has one recipe and
       // one definition of done; without this an agent converts the page it landed on and stops.
-      instructions: "When the user asks to make a site or all of its pages editable, to convert it, or to componentize the whole site: this is playbook \xA713. Read `bettercms://playbook/schema` \xA713, call get_binding_report and get_conversion_brief { complete: true }, convert EVERY route the brief lists, and finish only when get_binding_report shows coverage.pending empty on every route \u2014 not when the first page works. On a workspace-wide connection pass projectId on every call; never ask the user to re-scope the connection. BetterCMS never executes a customer's Section renderer or app code. An ordinary MCP connection is not a push runner: explicitly poll list_section_validation_requests, claim one request at an exact git commit, run implementation and responsive checks inside the user's own repository and real app shell, then submit manifest + validation with that requestId and complete it\u2014or truthfully fail it when implementation/evidence is missing. Never invent a manifest, a passing validation, or visual evidence; these tools cannot grant the separate human Visual Approval required for publication."
+      instructions: "When the user asks to make a site or all of its pages editable, to convert it, or to bind its fields: this is playbook \xA713. Read `bettercms://playbook/schema` \xA713, call get_binding_report and get_conversion_brief { complete: true }, convert EVERY route the brief lists, and finish only when get_binding_report shows coverage.pending empty on every route \u2014 not when the first page works. On a workspace-wide connection pass projectId on every call; never ask the user to re-scope the connection. When the user asks to componentize the whole site, to turn every section into a component, or to build a component library from the site: this is playbook \xA712. Read `bettercms://playbook/schema` \xA712, start with get_site_composition, and use the batch tools \u2014 create_components, compose_pages, update_layout with `commands`, publish_components \u2014 rather than one call per component. Finish with get_site_composition and tell the user what the platform does not model (cookie banners, modals, breadcrumbs, pagination) and which components still need the owner's approval in the dashboard before they can be published. BetterCMS never executes a customer's Section renderer or app code. An ordinary MCP connection is not a push runner: explicitly poll list_section_validation_requests, claim one request at an exact git commit, run implementation and responsive checks inside the user's own repository and real app shell, then submit manifest + validation with that requestId and complete it\u2014or truthfully fail it when implementation/evidence is missing. Never invent a manifest, a passing validation, or visual evidence; these tools cannot grant the separate human Visual Approval required for publication."
     }
   );
   server.registerResource(