@bettercms-ai/mcp 0.36.0 → 0.37.1

package/dist/index.js

@@ -2209,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.",
@@ -2461,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"),
@@ -2497,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"),
@@ -2526,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(),
@@ -2537,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"
     ),
@@ -2548,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")
   });
@@ -3046,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",
@@ -3602,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 }
+        );
       }))
     },
     {
@@ -3628,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 } : {}
+            }))
           );
         })
       )
@@ -3669,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: {
@@ -3846,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
@@ -4143,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:
@@ -4160,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
@@ -4339,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"\`,
@@ -4425,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
@@ -4511,6 +4874,8 @@ ${FORM_FLOW}
 
 ${COMPONENT_FLOW}
 
+${COMPONENTIZE_SITE_FLOW}
+
 ${LAYOUT_FLOW}
 
 ${BUILD_SITE_FLOW}
@@ -4662,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",
     {
@@ -4804,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(