@bettercms-ai/mcp 0.72.1 → 0.73.0

package/dist/index.js

@@ -2540,6 +2540,7 @@ var STRUCTURE_PLAYBOOK_URI = "bettercms://playbook/structure";
 var STRUCTURE_DEFAULT_INSTRUCTION = `After you create collections or pages, organise them per the structure playbook: read ${STRUCTURE_PLAYBOOK_URI}, call suggest_content_structure (read-only), show the user its outline, then apply it with set_content_structure and the version it returned (the If-Match). A project that already has a structure keeps it: file only what you created, with move_to_folder, unless the user asks for a full re-organisation.`;
 var SKILLS_ROUTING_INSTRUCTION = "Before writing code in a repo that uses BetterCMS, explore the repo, then read the installed `bettercms` skill (`npx @bettercms-ai/install --project -y` adds it if missing): its table turns what you found into the one reference the task needs \u2014 read only that. Without the skill installed, read the same files as resources: bettercms://skill/bettercms, then bettercms://skill/<reference>.";
 var DOCK_UI_ROUTING_INSTRUCTION = "How fields and props look in the editor (groups, tabs, rows, icons, item names) is playbook \xA714 or the `field-ui` prompt: write it with update_content_model field* or update_component prop* plus ifMatch, read it back, and finish when get_next_steps reports no dock-* step.";
+var PUBLISH_HOLD_INSTRUCTION = "An item an author held back from site publishes (`publishHeldAt` set) stays out of whole-site publishes: do not publish it unless the user names it; publish_entries `release` includes it again.";
 var RECEIPT_FIRST_INSTRUCTION = "Start every project with get_next_steps: its `receipt` lists what is already done (`done`), what is still missing (`missing`, each item citing the count it reacted to) and the one `nextAction`. Work from that receipt instead of re-reading the site, call get_next_steps again after each batch of edits, and before you tell the user you are finished. On an imported site the gate is the definition of done: run `receipt.gate.nextAction`, read again, and repeat until `receipt.complete` is true. Record a gap you cannot close with editor_setup `exempt` only for an allowed reason that is true, with a note, never in prose.";
 var NEXT_STEPS_DESCRIPTION = `Call this FIRST on a project. Returns \`receipt\` \u2014 \`done\` (live release, bound elements, conversion coverage, composed pages, published components and Layout), \`missing\`, \`nextAction\` and \`notes\` (unjudged: unknown, not done) \u2014 plus \`data\`, the unfinished items by \`ruleId\` (skill finish-site lists them). Each item cites its count and may carry \`payload\` {rows, total}, at most 20 rows. \`receipt.complete\` is the setup gate's verdict and \`receipt.gate\` its numbers per built route. Run \`receipt.gate.nextAction\`, call it again after each batch; you are finished only when \`complete\` is true. \`organise-content\`: pages and collections are in no folder \u2014 read ${STRUCTURE_PLAYBOOK_URI}, call suggest_content_structure and, once the user agrees, set_content_structure.`;
 var LAYOUT_CHROME_INSTRUCTION = 'When the user asks to make the navigation, footer or other site chrome editable, or get_next_steps lists a `layout-*` or `chrome-duplicated` item: this is playbook \xA711 item 3. Chrome is the project Layout, never page fields: in the source, wrap each Section in `data-bcms-layout-section` (the slot, its base slug) and mark each value `data-bcms-layout-field="layout:<sections[slug].id>:<fieldId>"`, never `data-bcms-field` inside it, then push; the strip removes the page copies, never delete them by hand. On a site BetterCMS serves, publish_layout writes Layout VALUES into the live pages; a structure change waits for a Rebuild. Never place nav, footer or modal blocks or fields on a page: the Layout (or the site\'s own layout) draws chrome, so a page copy either duplicates it or renders nowhere (get_componentize_plan reports one as LAYOUT_CHROME).';
@@ -2898,6 +2899,7 @@ var LISTING_TAIL = /* @__PURE__ */ new Set([
   "apply_branch",
   "generate_image",
   "transform_image",
+  "write_alt_text",
   // The ABM campaign lane — also hidden from the default listing (ABM_TOOLS below).
   "research_account",
   "build_abm_page",
@@ -2950,10 +2952,11 @@ var WEBHOOK_EVENTS = [
   "deployment.triggered"
 ];
 var NEW_TOOL_TEXT = {
+  save_reusable_block: "Copy a page section (its layout, values and design) into Saved blocks in the section library, under `name`. The page is not changed; a block placed from Saved blocks is an independent section.",
   search_content: "Full-text search over the project's PUBLISHED pages and entries (the site-search index). Returns id, type ('page'|'entry'), title, slug and a snippet per hit; `type` narrows to one kind. Drafts are not indexed: find those with list_content_entries `where`. `meta.unavailable` means site search is off for this project.",
   discard_draft: "Throw away unpublished edits to an entry (`entryId`) or a page (`pageId`) \u2014 exactly one: the draft returns to exactly what is live and `pendingChanges` becomes false. A page resets its blockJson and its published Layout overrides. 409 no_published_version means it was never published (delete it instead). Pass ifMatch (optimisticVersion) to refuse if it changed since you read it.",
   give_feedback: "Tell the BetterCMS team about a tool that failed, a capability you needed and did not have, or docs that misled you. Opens a ticket for the team; nothing in the project changes. Name the `tool`, and paste the request and response into `context`. Never include secrets or personal data.",
-  publish_entries: "Publish or unpublish many entries and pages in ONE call (up to 100 ids of each; pages publish only). Needs a publish-enabled connection, and each item still passes its own gates (editorial stage, required fields). Nothing stops the run: the result lists what changed (`published` or `unpublished`) and every refusal in `failed` with its reason. A publish answers 202 with the routes being rebuilt.",
+  publish_entries: "Publish or unpublish many entries and pages in ONE call (up to 100 ids of each; no page unpublish). Needs a publish-enabled connection, and each item still passes its own gates (editorial stage, required fields). Nothing stops the run: the result lists what changed (`published` or `unpublished`) and every refusal in `failed` with its reason. A publish answers 202 with the routes being rebuilt. `hold` keeps a live item's edits out of whole-site publishes, `release` includes them again; publishing a held item here ends its hold.",
   create_content_entries: "Create up to 200 DRAFT entries of one collection in ONE call, each {slug?, data} as create_content_entry takes it. Every row reports `created` (with id and slug) or `failed` (with the error), a failure does not stop the others, and `meta` counts them. A row with `externalKey` is safe to send again: its entry is `updated` (draft only), or `unchanged` when the row is the same. A row setting a developer-locked field fails (FIELD_LOCKED). Publish afterwards with publish_entries.",
   translate_entry: "Create an entry's `targetLocale` translation with AI (uses AI credits: 402/403 when out or not on the plan). Text and longtext fields are translated; rich text and documents are copied for you to translate; the rest is copied. The new entry is a DRAFT with `locale` set and `translationOf` = the source; `meta` lists translated and copied keys. `targetLocale` must be one of the project's locales; 409 locale_conflict means that translation exists, so edit it instead.",
   list_webhooks: "List the project's outgoing webhooks: name, url, events, whether active, and delivery health (total, failed, last attempt). Signing secrets are never returned.",
@@ -2966,7 +2969,8 @@ var NEW_TOOL_TEXT = {
   refresh_search_index: "Tell search engines and site search about published changes; costs nothing. action 'indexnow' submits `urls` (this site's own, up to 1000) to IndexNow, or every change since the last submission when omitted. action 'reindex' rebuilds the project's site-search index. 503 means the index is unreachable: try again later.",
   import_redirects: "Bulk-create redirects for a migration, from `rows` or from `text` in `format` (our CSV export, a Netlify `_redirects` file, or a vercel.json). Call it with `dryRun: true` FIRST: nothing is written and each row comes back `would-create`, `existing` or `skipped` with a reason. Rows get create_redirect's rules. Max 5000.",
   editor_setup: "Make the live build editable. A build imports only SEO/meta, media, brand and the models bcms-content.json declares; this derives the rest from the live release: pages, collections, forms, bindings, button and section components (when the authoring preference is components), Component Groups and the Content sidebar. Run it after an import or a rebuild, before the conversion brief. Idempotent: `ready` when it already ran for the live sha, else it starts (`running`; poll with `check: true` or get_deploy_status `editorSetup`). `state`: never or stale (run it), running, ready, failed. 409 = nothing is live yet: deploy first. Then get_next_steps.",
-  transform_image: "Edit an existing Media Library image with an instruction (e.g. 'remove the background', 'make it dusk'); the result is saved as a NEW asset and the original is kept (5 AI credits). Returns the new asset (id, url, altText)."
+  transform_image: "Edit an existing Media Library image with an instruction (e.g. 'remove the background', 'make it dusk'); the result is saved as a NEW asset and the original is kept (5 AI credits). Returns the new asset (id, url, altText).",
+  write_alt_text: "Alt text for a Media Library image (mediaId) or an https image URL (url), written from its pixels (1 AI credit). A suggestion: save it with update_media."
 };
 var DELETE_PAGE_RUNTIME_BUNDLE = " Or, with no pageId, `runtimeBundle`: 'report' lists the duplicate pages derived from a server app's own bundle (`app/` folders); 'apply' retires them and their empty folders.";
 var FIELD_LOCKED_NOTE = "A readOnly 'developer' field keeps its stored value: changing or omitting it without schema access is 403 FIELD_LOCKED.";
@@ -3025,7 +3029,8 @@ var SEO_KEY_TEXT = {
   indexnowConfig: "IndexNow on publish, minus URL patterns to leave out",
   searchConfig: "site search: on/off, the box's placeholder, AI answers"
 };
-var VARIANT_GROUP_NOTE = "When the component belongs to a family of looks, `variantGroup` names the family and lists its looks.";
+var VARIANT_GROUP_NOTE = "`variantGroup`: the family of looks it belongs to, if any, and its looks.";
+var DETACHED_COPY_NOTE = "{overrides?}: a rich-text embed's separate-copy `fields` (playbook \xA75)";
 var UNPROPPED_COPY_NOTE = "A `warnings` entry UNPROPPED_COPY names copy no prop targets, which nobody can edit: add a prop with a `target` for each leaf it lists.";
 var UPDATE_PAGE_IF_MATCH_NOTE = "get_page's `optimisticVersion`: the write applies only at that version, and a 409 means the page changed since, so read it again. Send it whenever you pass blockJson, which REPLACES the whole composition.";
 var SLOT_MULTIPLE_NOTE = "'slot' with config.multiple holds a list [{componentId, overrides?}] (config.maxItems, default 12, at most 50): target.path 'props.children' on a section. V2 slots, 'table' mode 'types': playbook \xA75.";
@@ -3260,7 +3265,13 @@ var propUiObject = uiObject.extend({
     collapsible: z.boolean().optional(),
     layout: z.enum(["stack", "breakpoints"]).optional(),
     order: z.number().int().min(0).max(99).optional()
-  }).optional().describe("the group this prop (or sub-field) sits in. The FIRST member defines {id, label, kind?, icon?, collapsed?, description?, columns?, collapsible?, layout?, order?}; later ones send only {id}.")
+  }).optional().describe("the group this prop (or sub-field) sits in. The FIRST member defines {id, label, kind?, icon?, collapsed?, description?, columns?, collapsible?, layout?, order?}; later ones send only {id}."),
+  tab: z.strictObject({
+    id: z.string().min(1).max(40),
+    label: z.string().min(1).max(20).optional(),
+    icon: uiObject.shape.icon,
+    order: z.number().int().min(0).max(99).optional()
+  }).optional().describe("TOP-LEVEL props only: the dock tab this prop sits in (a V2 kit schema `groups` entry: Content, Design, \u2026). The FIRST prop in a tab defines {id, label, icon?, order?}; later ones send only {id}. \u22648 tabs, labels unique; a group's members share one tab.")
 });
 var choiceOption = z.union([z.string(), z.object({ label: z.string(), value: z.string(), icon: z.string().optional(), description: z.string().optional() })]);
 var fieldShape = {
@@ -3279,7 +3290,7 @@ var fieldShape = {
     "choices when type is 'select'. A plain string, or {label, value, icon?, description?} when the stored value differs from what the editor shows (e.g. {label:'Sold out', value:'soldOut'}); icon a dock name, description one line \u2264140."
   ),
   config: z.record(z.string(), z.unknown()).optional().describe(
-    "per-type config: reference {contentModelId}, multi-reference {contentModelId,min,max}, array {itemType: text|number|date|image|link|richtext}, date {includeTime, timezone}, modular|slot {blockSlugs: ['quote','gallery'], minItems?, maxItems?} (slot: playbook \xA75) \u2014 blockSlugs is REQUIRED, non-empty, and each slug must name an existing kind:'block' model; richtext {inline:true, hostTag:'h2', accept:['h2','p','b','i','u','link'], features:['bold','italic','underline','link','headings'], allowMultipleParagraphs:false} \u2014 for a field bound to ONE element on the page: `hostTag` is that element's tag and `accept` must name it, so the editor's block-style control opens already showing 'Heading 2' instead of 'Paragraph'. Name exactly ONE heading level: publish refuses an <h3> value bound to an <h2> rather than nesting one heading inside the other. Keep 'p' in `accept` or the sanitiser strips a block demoted to Paragraph; limits: text/longtext {minLength,maxLength,pattern,patternMessage}, richtext {minLength,maxLength}, number {validation:{min,max}}, array {minItems,maxItems}, tags {min,max}, rating {min,max,step}"
+    "per-type config: reference {contentModelId}, multi-reference {contentModelId,min,max}, repeater {minItems, maxItems} (the list's item limits; the editor shows 'max N' and stops Add there), array {itemType: text|number|date|image|link|richtext}, date {includeTime, timezone}, modular|slot {blockSlugs: ['quote','gallery'], minItems?, maxItems?} (slot: playbook \xA75) \u2014 blockSlugs is REQUIRED, non-empty, and each slug must name an existing kind:'block' model; richtext {inline:true, hostTag:'h2', accept:['h2','p','b','i','u','link'], features:['bold','italic','underline','link','headings'], allowMultipleParagraphs:false} \u2014 for a field bound to ONE element on the page: `hostTag` is that element's tag and `accept` must name it, so the editor's block-style control opens already showing 'Heading 2' instead of 'Paragraph'. Name exactly ONE heading level: publish refuses an <h3> value bound to an <h2> rather than nesting one heading inside the other. Keep 'p' in `accept` or the sanitiser strips a block demoted to Paragraph; limits: text/longtext {minLength,maxLength,pattern,patternMessage}, richtext {minLength,maxLength}, number {validation:{min,max}}, array {minItems,maxItems}, tags {min,max}, rating {min,max,step}"
   ),
   fields: z.array(z.lazy(() => fieldObject)).optional().describe(
     "NESTED child fields \u2014 REQUIRED for type 'group' (one nested object, a Non-Repeatable Zone like blog_hero \u2192 heading, description, hero_image) and type 'repeater' (a repeatable array of such objects, a Repeatable Zone / section-list like testimonials \u2192 quote, author). A section with repeating items is a 'repeater'; a fixed grouped block is a 'group'. Recurse to any depth \u2014 do NOT flatten zones into separate top-level fields."
@@ -3450,7 +3461,8 @@ function toField(f) {
     return { ...base, type: "array", config: { zones: { nonRepeatable: toFields(f.fields) } } };
   }
   if (f.type === "repeater") {
-    return { ...base, type: "array", config: { zones: { repeatable: { fields: toFields(f.fields) } } } };
+    const { minItems, maxItems } = f.config ?? {};
+    return { ...base, type: "array", config: { zones: { repeatable: { fields: toFields(f.fields), ...minItems !== void 0 ? { minItems } : {}, ...maxItems !== void 0 ? { maxItems } : {} } } } };
   }
   if (f.type === "array" && f.config && typeof f.config === "object" && "zones" in f.config) {
     const zones = f.config.zones ?? {};
@@ -3483,8 +3495,8 @@ var UPDATE_MODEL_DESCRIPTION = "Edit a content model: rename it, change descript
 var FIELD_REMOVAL_NOTE = "top-level field keys (from get_content_model) to DELETE from this model with every entry's value for them; needs allowFieldRemoval: true. An unknown key refuses the whole call. Never for a rename: rename the label instead.";
 var ALLOW_FIELD_REMOVAL_NOTE = "true = the user accepts that removeFields discards those fields' data in every entry. There is no dry run on this route: confirm first.";
 var MODEL_IF_MATCH_NOTE = "optimisticVersion from get_content_model (with pageId: get_page backingModel). The write applies only at that version; a 409 version-conflict means it changed since: read it again and re-apply, never retry blindly. REQUIRED with field*, override or a fieldset kind/tab/icon/collapsed (428 without); otherwise, omitted, the last write wins.";
-var COMPONENT_IF_MATCH_NOTE = "optimisticVersion from get_component. The write applies only at that version; a 409 version-conflict means it changed since: read it again and re-apply. REQUIRED with prop*, override or a prop ui icon/itemLabel/group (428 without).";
-var PROP_UI_ARG_NOTE = "top-level prop key \u2192 ui patch, the same vocabulary as a prop's `ui`: each key merges, a null key clears it, null clears the whole ui";
+var COMPONENT_IF_MATCH_NOTE = "optimisticVersion from get_component. The write applies only at that version; a 409 version-conflict means it changed since: read it again and re-apply. REQUIRED with prop*, override or a prop ui icon/itemLabel/group/tab (428 without).";
+var PROP_UI_ARG_NOTE = "top-level prop key \u2192 ui patch, the same vocabulary as a prop's `ui` (group and tab included): each key merges, a null key clears it, null clears the whole ui. Patches keep every other prop as stored; sending `props` instead REPLACES the whole array, so echo each prop's stored `ui` (its `ui.group` AND `ui.tab`) or the prop leaves its tab";
 var OVERRIDE_NOTE = "replace chrome a person set (otherwise 409 ui_human_owned names those paths). Send it only on the user's word.";
 var FIELD_UI_ARG_NOTE = "path \u2192 ui patch, a field's `ui` vocabulary: each key merges, a null key clears it, null clears the whole ui";
 var MODEL_UPDATE_KEYS = [
@@ -3713,7 +3725,7 @@ function buildToolDefs(deps) {
       "per-type props: heading {text, level}; text/richtext {html} (NOT {text}), and both also take level 1-6, rendering the html AS that <hN> with inline marks kept (one line of inline copy only) \u2014 use it for a title that carries a styled span; image {src, alt}; button {text, href, variant? (hosted pages; else a Button component), size? sm|md|lg, fullWidth?, arrow? boolean, icon? ui.icon name, newTab? boolean, rel? nofollow|sponsored|ugc}; spacer {height}; video {url}; form {formId}; component {componentId, overrides?}; navbar {links:[{label,href}], logo?, cta?}; footer {columns, copyright?}; section {children: block[]}; columns {columns: block[][], gap} \u2014 a column may hold ANY block; slider {slides:[{id,children}]}; tabs {tabs:[{id,label,children}]}; collection {cardComponentId?, source? {modelId}, limit?, filters?, sort?, pinnedIds?, excludeCurrent?}: a collection's published entries as cards (every prop: skill content-modeling)"
     ),
     style: z.record(z.string(), z.unknown()).optional().describe(
-      "design tokens: theme, bg (none|surface|muted|accent|dark|custom), bgCustom hex, paddingTop/paddingBottom/paddingSides px, contentWidth (narrow|default|wide|full), align, corner, shadow, borderTop/borderBottom, border (all four sides, in the text colour), hideOn [mobile|tablet|desktop], never all three. A real marketing band is a `section` block carrying bg + padding + contentWidth."
+      "design tokens: theme, bg (none|surface|muted|accent|dark|custom), bgCustom hex, paddingTop/paddingBottom/paddingSides px, contentWidth (narrow|default|wide|full), align, corner, shadow, borderTop/borderBottom, border (all four sides, in the text colour), hideOn [mobile|tablet|desktop] (all three hides it on the page: kept in the draft, never published). A real marketing band is a `section` block carrying bg + padding + contentWidth."
     ),
     window: windowArg.nullable().optional().describe(WINDOW_NOTE)
   });
@@ -4092,6 +4104,7 @@ function buildToolDefs(deps) {
     ),
     propUi: z.record(z.string(), z.record(z.string(), z.unknown()).nullable()).optional().describe(PROP_UI_ARG_NOTE),
     propGroup: z.record(z.string(), z.record(z.string(), z.unknown()).nullable()).optional().describe("prop key \u2192 its ui.group ({id, label?, kind?, icon?, collapsed?}), null takes it out"),
+    propTab: z.record(z.string(), z.record(z.string(), z.unknown()).nullable()).optional().describe("prop key \u2192 its ui.tab ({id, label?, icon?, order?}), the V2 schema group it sits in. The FIRST top-level prop in a tab defines {id, label, icon?, order?}, later ones send {id}; \u22648 tabs; one group's members share one tab. null takes it out"),
     propLabel: z.record(z.string(), z.string().min(1).max(255)).optional().describe("prop key \u2192 label"),
     propHelpText: z.record(z.string(), z.string().max(200).nullable()).optional().describe("prop key \u2192 help text, null clears it"),
     override: z.boolean().optional().describe(OVERRIDE_NOTE),
@@ -4120,7 +4133,8 @@ function buildToolDefs(deps) {
     componentId: z.string().min(1).describe("component id (from list_components)")
   });
   const getComponentInput = z.object({
-    componentId: z.string().min(1).describe("component id (from list_components)")
+    componentId: z.string().min(1).describe("component id (from list_components)"),
+    detachedCopy: z.object({ overrides: z.record(z.string(), z.unknown()).optional() }).optional().describe(DETACHED_COPY_NOTE)
   });
   const publishComponentsInput = z.object({
     componentIds: z.array(z.string().min(1)).min(1).max(100).describe("component ids (from list_components)")
@@ -4428,6 +4442,13 @@ ${d.outline}` : "Proposed Content structure.", d);
         z.object({ redirectId: z.string().min(1) }).shape,
         async (c, a) => ok("Deleted redirect.", await data(c, "DELETE", `/management/redirects/${s(a.redirectId)}`))
       ),
+      def(
+        "save_reusable_block",
+        "Save a section as a reusable block",
+        NEW_TOOL_TEXT.save_reusable_block,
+        z.object({ pageId: z.string().min(1), blockId: z.string().min(1).describe("a top-level section id (get_page)"), name: z.string().min(1).describe("80 characters at most; a longer one is refused as SAVED_BLOCK_NAME_TOO_LONG") }).shape,
+        async (c, a) => ok("Saved the section as a reusable block.", await data(c, "POST", `/management/saved-blocks`, { pageId: a.pageId, blockId: a.blockId, name: a.name }))
+      ),
       def(
         "get_seo",
         "Get site SEO",
@@ -5022,14 +5043,14 @@ ${d.outline}` : "Proposed Content structure.", d);
         "Publish or unpublish many entries and pages",
         NEW_TOOL_TEXT.publish_entries,
         z.object({
-          action: z.enum(["publish", "unpublish"]).describe("take the items live, or back to draft"),
+          action: z.enum(["publish", "unpublish", "hold", "release"]).describe("live, back to draft, or hold/release from site publishes"),
           entryIds: z.array(z.string().min(1)).max(100).optional().describe("entry ids (from list_content_entries)"),
-          pageIds: z.array(z.string().min(1)).max(100).optional().describe("page ids (from list_pages); publish only")
+          pageIds: z.array(z.string().min(1)).max(100).optional().describe("page ids (from list_pages); not for unpublish")
         }).shape,
         async (c, a) => {
           const receipt = await data(c, "POST", `/management/publish`, { action: a.action, entryIds: a.entryIds, pageIds: a.pageIds });
           const outcome = receipt?.outcome;
-          return ok(a.action === "publish" ? publishedLines(outcome, "Publish receipt.").join("\n") : "Unpublish receipt.", receipt);
+          return ok(a.action === "publish" ? publishedLines(outcome, "Publish receipt.").join("\n") : a.action === "unpublish" ? "Unpublish receipt." : "Hold receipt.", receipt);
         }
       ),
       def(
@@ -5141,6 +5162,13 @@ ${d.outline}` : "Proposed Content structure.", d);
         }).shape,
         async (c, a) => ok("Edited image (a new asset).", await data(c, "POST", `/management/ai/image/transform`, { mediaId: a.mediaId, prompt: a.prompt, altText: a.altText, folderId: a.folderId }))
       ),
+      def(
+        "write_alt_text",
+        "Write alt text with AI",
+        NEW_TOOL_TEXT.write_alt_text,
+        z.object({ mediaId: z.string().min(1).optional().describe("the image (from list_media)"), url: z.string().optional().describe("or an https image URL") }).shape,
+        async (c, a) => ok("Alt text suggestion.", await data(c, "POST", `/management/ai/alt-text`, a.url ? { url: a.url } : { mediaId: a.mediaId }))
+      ),
       def(
         "list_activity",
         "List project activity",
@@ -5509,6 +5537,8 @@ ${d.outline}` : "Proposed Content structure.", d);
               language: p.language,
               pageType: p.pageType,
               status: p.status,
+              // Held back from whole-site publishes: only when set, so an unheld list stays the same size.
+              ...p.publishHeldAt ? { publishHeldAt: p.publishHeldAt } : {},
               fields: p.fields
             }))
           );
@@ -6019,11 +6049,18 @@ ${notes.join("\n")}` : summary, created);
       name: "get_component",
       config: {
         title: "Get a component (with its blockJson)",
-        description: "Get one component by id INCLUDING its blockJson tree and props (with any stored `ui` authoring chrome on them; `stale: true` = no placement renders it). Read this before update_component so you keep the existing blocks, and after declaring field UI as the receipt that it landed \u2014 a prop absent here was not stored. " + VARIANT_GROUP_NOTE,
+        description: "One component with its blockJson and props (stored `ui` on them; `stale: true` = no placement renders it). Read it before update_component to keep its blocks, and after declaring field UI: a prop absent here was not stored. " + VARIANT_GROUP_NOTE,
         inputSchema: getComponentInput.shape
       },
       handler: guard(
         async (args) => withClient(async (client) => {
+          if (args.detachedCopy) {
+            const res = await client.fetchJSON(
+              client.url(`/management/components/${encodeURIComponent(args.componentId)}/detached-copy`),
+              { method: "POST", body: JSON.stringify(args.detachedCopy) }
+            );
+            return ok(`A separate copy of '${res.data.name}': store \`fields\` on the embed.`, res.data);
+          }
           const cmp = await client.getComponent(args.componentId);
           return ok(`Component '${cmp.name}' (${cmp.blockJson.length} block(s)).`, cmp);
         })
@@ -6549,6 +6586,16 @@ component). A list of several item shapes on a component is a \`table\` prop wit
 \`config.mode: 'types'\` and \`config.itemTypes: [{ name, label?, fields }]\`, rows
 \`[{ _key?, _type: '<name>', ...values }]\`.
 
+A component inside a \`richtext\` value is \`{ _type: 'bcmsBlock', _key, schemaKey: 'component',
+schemaLabel?, fields: { componentId, overrides?, variant? } }\` and FOLLOWS the component: publishing
+it changes this place. A SEPARATE COPY stops following it: \`fields: { componentId, detached: true,
+props, blocks, sourcePublishedAt, variant? }\`, exactly as \`get_component { componentId,
+detachedCopy: { overrides } }\` returns them. It renders its own \`blocks\`; \`componentId\` stays so
+it can be linked again (write the linked shape), and a \`sourcePublishedAt\` older than the
+component's \`lastPublishedAt\` (every publish; \`publishedAt\` is the first) means the shared
+version changed since. Refused by name:
+\`component_copy_invalid\`, \`component_copy_not_frozen\`.
+
 ## 5b. NEVER MODEL SEO. It is native.
 
 Do not create \`seoTitle\`, \`metaTitle\`, \`metaDescription\`, \`ogImage\`, \`canonicalUrl\`,
@@ -7187,8 +7234,11 @@ conversion is yours to write.
    markup inside a \`text\` field.
    **Prose MIGRATED from another CMS needs one extra check.** Every block's \`_type\` must be one
    this platform stores \u2014 \`block\`, \`table\` (\`{_type:"table", rows:[{_key, cells:[{_key,
-   content:[...blocks], header?}]}]}\`; Sanity's row of plain strings, \`rows:[{cells:["a","b"]}]\`,
-   is admitted too), \`bcmsCode\`, \`bcmsDivider\`, \`bcmsMention\`, or \`bcmsBlock\` carrying a
+   content:[...blocks], header?, group?}], group?}], caption?, notes?, rowGroups?, columnGroups?}\`,
+   groups \`[{_key, label}]\`; Sanity's row of plain strings, \`rows:[{cells:["a","b"]}]\`,
+   is admitted too), \`bcmsCode\`, \`bcmsDivider\`, \`bcmsMention\`, \`pullQuote\`
+   (\`{quote, name, role?, link?}\`), \`keyTakeaways\` (\`{title?, points:[...strings]}\`,
+   title at most 40 characters, at most 8 points), or \`bcmsBlock\` carrying a
    \`schemaKey\` \u2014 and a foreign node (a Sanity image, \`{_type:"image", asset:{_ref}}\`, for one)
    is not merely unrendered: it has no component here, so it
    vanishes from the HTML every delivery surface reads while the stored value still looks whole.
@@ -7354,8 +7404,13 @@ them \u2014 except on a \`slot\`, whose children belong to whichever component f
 cannot be resolved at save time. \`update_component\` REPLACES the whole \`props\` array, so echo
 back each prop's stored \`ui\` or you delete it along with the prop. Props have no fieldsets, so a
 prop joins a group with \`ui.group\`: the FIRST prop of a group defines \`{ id, label, kind?, icon?,
-collapsed? }\` (kind \`group\` or \`row\`, never \`tab\`), and every later prop sends \`{ id }\` only. A
-FIELD never takes \`ui.group\`; it joins a fieldset with \`fieldsetId\`.
+collapsed? }\` (kind \`group\` or \`row\`; a tab is \`ui.tab\`, never a group kind), and every later prop
+sends \`{ id }\` only. A prop joins a TAB with \`ui.tab\` the same way: the FIRST top-level prop in a tab
+defines \`{ id, label, icon?, order? }\`, later props send \`{ id }\`; at most 8 tabs, labels \u226420 characters
+and unique; top-level props only (never a sub-field); all members of one \`ui.group\` share one tab. A V2
+kit entry's schema \`groups\` and each field's \`group\` map 1:1 to \`ui.tab\`, so its \`design\` group is a
+tab named Design holding the theme, sticky and similar props. A FIELD never takes \`ui.group\` or
+\`ui.tab\`; it joins a fieldset with \`fieldsetId\`.
 
 \`\`\`jsonc
 { "key": "slides", "label": "Slides", "type": "table",
@@ -7424,13 +7479,13 @@ Importance orders a screen: required fields first, then array order.
 | A star rating | \`type: 'rating'\`: a number from 0 to \`config.max\` (5), \`config.step\` 1 or 0.5 (\`rating_value_invalid\`) |
 | A code snippet | \`type: 'code'\`: \`{ language?, code }\` or a string; \`config.language\` default, \`config.languages\` allowlist (\`code_value_invalid\`) |
 | "Add question" instead of "Add item" | \`ui.itemLabel: 'Question'\` (V2 \`itemNoun\`; there is no itemNoun key) |
-| The same section as a component (the dock edits a page section through its props) | the same keys on its \`props\`: \`type: 'object'\` with \`config.fields\` (\`group\` and \`table\` too, 10 levels), \`datetime\`, \`slug\`, \`email\`, \`phone\`, \`json\`, \`location\`, \`tags\`, \`rating\`, \`code\`, plus the two CMS-item types (\`reference\`, \`multi-reference\`: \`config.contentModelId\` or \`polymorphic\` + \`allowedModelSlugs\`; page reads hydrate them, a text slot shows the title), and every key above except fieldsets (props group with \`ui.group\`) |
+| The same section as a component (the dock edits a page section through its props) | the same keys on its \`props\`: \`type: 'object'\` with \`config.fields\` (\`group\` and \`table\` too, 10 levels), \`datetime\`, \`slug\`, \`email\`, \`phone\`, \`json\`, \`location\`, \`tags\`, \`rating\`, \`code\`, plus the two CMS-item types (\`reference\`, \`multi-reference\`: \`config.contentModelId\` or \`polymorphic\` + \`allowedModelSlugs\`; page reads hydrate them, a text slot shows the title), and every key above except fieldsets (props group with \`ui.group\` and tab with \`ui.tab\`) |
 
 An unknown \`openMode\` is refused with \`openMode_invalid\`, one on a leaf \`openMode_leaf\`; a bad \`config.scale\` with \`scale_invalid\`; more than 10 nested field levels with \`field_depth_exceeded\`. update_field sets and clears (null) helpMore, advanced, recommendedMax and openMode on an existing field.
 
 **Tabs.** A \`kind: 'tab'\` fieldset is a tab:
 - at most **3** tabs, names at most 20 characters and unique;
-- top-level fields only: tabs never nest and props never take them;
+- top-level fields only: tabs never nest (a component's props take tabs through \`ui.tab\`, its own rules);
 - untabbed fields stay PINNED above the strip;
 - a group or row fieldset joins a tab with \`tab: '<tab id>'\`; groups in a non-first tab default open;
 - with fewer than 2 non-empty tabs no strip renders, so a tab for one fieldset is noise.
@@ -7449,7 +7504,7 @@ An unknown \`openMode\` is refused with \`openMode_invalid\`, one on a leaf \`op
   \`fieldLabel\`, \`fieldHelpText\` (keyed by dotted key path, \`'hero.title'\`) and \`fieldsets\`. A page's
   schema: the same call with \`pageId\` instead of \`modelId\`, and the version from \`get_page\`'s
   \`backingModel\`.
-- A component's props: \`update_component\` with \`propUi\`, \`propGroup\`, \`propLabel\`, \`propHelpText\` (keyed by prop key).
+- A component's props: \`update_component\` with \`propUi\`, \`propGroup\`, \`propTab\`, \`propLabel\`, \`propHelpText\` (keyed by prop key).
   Name props from the code (\`plan.cents\` \u2192 Cents); help text guides ("Whole number, no currency symbol."), never repeats
   the value; repeated cards are one \`table\` prop. An icon (\`config.media: "icon"\`) is content: group it, never prune it.
   They write the DRAFT props; no publish is needed for the editor to show them.
@@ -7462,6 +7517,8 @@ An unknown \`openMode\` is refused with \`openMode_invalid\`, one on a leaf \`op
 - **409** \`ui_human_owned\` \u2014 a person shaped those paths. Leave them, or send \`override: true\`, and
   only when the user said so.
 - \`tab_unknown\`, \`tab_nested\`, \`tab_props\`, \`tab_max\`, \`tab_name\`, \`tab_depth\` \u2014 the tab rules above.
+- \`prop_tab_unknown\`, \`prop_tab_redefined\`, \`prop_group_split_tabs\` \u2014 a prop's \`ui.tab\` rules (\`tab_max\`,
+  \`tab_name\` and \`tab_nested\` too); \`tab_props\` is a \`ui.group\` with \`kind: 'tab'\` \u2014 use \`ui.tab\`.
 - \`fieldset_unknown\` / \`fieldset_orphan\` \u2014 a \`fieldsetId\` naming no fieldset, or a list that drops a
   fieldset its fields still name.
 - \`row_member_type\`, \`row_member_count\`, \`row_member_control\` \u2014 the row rule.
@@ -7587,7 +7644,7 @@ shape, then ask me, once and batched). Icon names are in bettercms://icons/dock.
    - fields that exist: \`update_content_model\` fieldUi / fieldFieldset / fieldOrder / fieldLabel /
      fieldHelpText by field path, plus \`fieldsets\`. A singleton page: send \`pageId\` instead of
      modelId, with its backingModel's version;
-   - component props: \`update_component\` propUi / propGroup / propLabel / propHelpText;
+   - component props: \`update_component\` propUi / propGroup / propTab / propLabel / propHelpText;
    - a NEW field: ui / helpText / showIf in the same \`add_field\` call, with \`after\`.
    A 409 \`ui_human_owned\` names chrome a person set: leave it, or ask me and send \`override: true\`
    only on my word.
@@ -8248,7 +8305,7 @@ function buildServer(deps) {
       // one definition of done; without this an agent converts the page it landed on and stops.
       instructions: RECEIPT_FIRST_INSTRUCTION + " 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. " + LAYOUT_CHROME_INSTRUCTION + " " + CTA_BUTTON_INSTRUCTION + " 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 componentize_sections, 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. " + // The default after authoring (the structure standard): organise what you made. Same
       // sentence as the hosted connector's MCP_INSTRUCTIONS.
-      STRUCTURE_DEFAULT_INSTRUCTION + " " + SKILLS_ROUTING_INSTRUCTION + " " + DOCK_UI_ROUTING_INSTRUCTION
+      STRUCTURE_DEFAULT_INSTRUCTION + " " + SKILLS_ROUTING_INSTRUCTION + " " + DOCK_UI_ROUTING_INSTRUCTION + " " + PUBLISH_HOLD_INSTRUCTION
     }
   );
   server.registerResource(