sbuilder-mcp 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -6,6 +6,29 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-09-07
+
+### Added
+- sb_add and sb_move now seed the same content the editor gives an element at drop time: satellite nodes such as an accordion's item skin or a tab's shared button, and seeded subtrees for a list's empty state and for dropdown, select and popover, which render as an empty box without them.
+- sb_page_open reports compose_warnings from the platform, including globalMissing, which means the server could not find a shared section's master and deleted the reference node from the document it handed back — saving from there makes the loss permanent.
+- sb_page_create reports slug_renamed when the requested slug was already taken; the platform silently stores a suffixed slug and answers success, so every link authored to the requested slug would otherwise be dead.
+- sb_publish reports not_published when a page has no saved draft, since the platform skips it and still answers success with whatever else did publish.
+- sb_review reports unlinked_form when a form element names no form, since it composes nothing and publishes as an empty box with no warning from the platform.
+- sb_review reports dead_menu_link when a menu has no entries or an entry has no href, since the renderer reads specials.menuItems and never menuId.
+- sb_review reports extra_repeater_child when a repeater element (such as list-dataset) carries more than one child, since only the first is ever rendered per record.
+
+### Changed
+- sb_add and sb_move now refuse adding or moving a second child into a repeater element, since only the first child renders; a reorder within the same parent is still allowed.
+- sb_duplicate now refuses duplicating into a repeater element for the same reason, and deep-copies satellite nodes (such as an accordion's skin) with the owner's pointer rewritten instead of aiming the copy at the original's satellite.
+- sb_duplicate strips the composition stamps (globalId, globalRef, globalKind, globalRev) from a duplicated node instead of copying them, since two nodes sharing one stamp is refused by the platform on the next save.
+- sb_publish now returns only the fields a caller acts on (pageId, slug, isHomepage) for each published page instead of the platform's full rendered document, html and css for every page the cascade touched.
+- sb_page_create's dry_run preview and live response now redact settings the same way sb_api_call does, since it is a free-form object a caller can pass a credential inside.
+- The internal tree walk used by sb_remove, sb_duplicate and save validation now follows satellite nodes (attached through config, not the child list) in addition to the child list, so removing or duplicating a node also handles its satellites correctly.
+- Save validation now refuses a document where a composition stamp (globalId, overlayId) sits on a node that is not a direct child of ROOT, or is duplicated across two nodes, since the platform refuses both later and reports it as an opaque error.
+
+### Fixed
+- Reordering a node within the same repeater parent no longer trips the new second-child guard.
+
 ## [0.2.0] - 2026-09-07
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,29 @@ Mọi thay đổi đáng chú ý của dự án được ghi lại trong file n
 Định dạng dựa trên [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 và dự án tuân theo [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-09-07
+
+### Added
+- sb_add và sb_move giờ seed đúng nội dung mà editor gán cho một element lúc kéo-thả: các node vệ tinh như skin của từng mục accordion hay nút dùng chung của tab, và các subtree được seed sẵn cho trạng thái rỗng của list cũng như cho dropdown, select và popover — vốn render thành hộp trống nếu thiếu chúng.
+- sb_page_open giờ báo cáo compose_warnings từ nền tảng, bao gồm globalMissing — nghĩa là server không tìm thấy bản gốc của một shared section và đã xóa node tham chiếu khỏi document trả về; lưu từ đây sẽ khiến việc mất đó thành vĩnh viễn.
+- sb_page_create giờ báo cáo slug_renamed khi slug yêu cầu đã bị chiếm; nền tảng âm thầm lưu một slug có hậu tố khác và trả về thành công, nên mọi link được gán theo slug yêu cầu ban đầu sẽ chết nếu không có cảnh báo này.
+- sb_publish giờ báo cáo not_published khi một trang chưa có draft đã lưu, vì nền tảng bỏ qua trang đó và vẫn trả về thành công kèm những trang khác đã publish được.
+- sb_review giờ báo cáo unlinked_form khi một form element không trỏ tới form nào, vì nó không compose được gì và publish thành một hộp trống mà nền tảng không hề cảnh báo.
+- sb_review giờ báo cáo dead_menu_link khi một menu không có entry nào hoặc một entry không có href, vì renderer chỉ đọc specials.menuItems chứ không đọc menuId.
+- sb_review giờ báo cáo extra_repeater_child khi một repeater element (như list-dataset) có nhiều hơn một child, vì chỉ child đầu tiên được render cho mỗi record.
+
+### Changed
+- sb_add và sb_move giờ từ chối thêm hoặc di chuyển child thứ hai vào một repeater element, vì chỉ child đầu tiên được render; việc sắp xếp lại thứ tự trong cùng một parent vẫn được cho phép.
+- sb_duplicate giờ cũng từ chối nhân bản vào một repeater element vì lý do tương tự, và deep-copy các node vệ tinh (như skin của accordion) kèm việc ghi lại con trỏ về đúng owner mới, thay vì để bản sao trỏ vào vệ tinh của bản gốc.
+- sb_duplicate giờ loại bỏ các stamp composition (globalId, globalRef, globalKind, globalRev) khỏi node được nhân bản thay vì sao chép nguyên trạng, vì hai node dùng chung một stamp sẽ bị nền tảng từ chối ở lần lưu kế tiếp.
+- sb_publish giờ chỉ trả về các trường mà caller thực sự dùng đến (pageId, slug, isHomepage) cho mỗi trang đã publish, thay vì toàn bộ document, html và css đã render của mọi trang mà cascade chạm tới.
+- Bản xem trước dry_run và phản hồi thật của sb_page_create giờ redact settings giống cách sb_api_call làm, vì đây là một object tự do mà caller có thể lỡ truyền credential vào.
+- Lượt duyệt cây nội bộ dùng bởi sb_remove, sb_duplicate và kiểm tra khi lưu giờ đi theo cả các node vệ tinh (gắn qua config, không qua child list) bên cạnh child list, nên việc xóa hoặc nhân bản một node giờ xử lý đúng cả các vệ tinh của nó.
+- Kiểm tra khi lưu giờ từ chối một document có stamp composition (globalId, overlayId) nằm trên node không phải con trực tiếp của ROOT, hoặc bị lặp trên hai node, vì nền tảng cũng từ chối cả hai trường hợp này nhưng báo lỗi mơ hồ ở bước sau.
+
+### Fixed
+- Sắp xếp lại một node trong cùng parent của repeater không còn bị chặn nhầm bởi guard child thứ hai mới thêm.
+
 ## [0.2.0] - 2026-09-07
 
 ### Added

package/dist/catalog/elements.generated.js

@@ -32969,3 +32969,572 @@ export const TRAIT_WRITES = {
         ]
     }
 };
+export const SATELLITE_RULES = {
+    "tab": [
+        {
+            "type": "tab-item",
+            "configKey": "tabItemId"
+        }
+    ],
+    "accordion": [
+        {
+            "type": "accordion-item",
+            "configKey": "accordionItemId"
+        }
+    ],
+    "menu": [
+        {
+            "type": "menu-item",
+            "configKey": "menuItemId"
+        },
+        {
+            "type": "menu-dropdown",
+            "configKey": "menuDropdownId"
+        }
+    ],
+    "cart-order": [
+        {
+            "type": "list-empty",
+            "configKey": "emptyStateId",
+            "seed": {
+                "type": "list-empty",
+                "children": [
+                    {
+                        "type": "icon",
+                        "style": {
+                            "color": "#d4d4d4"
+                        },
+                        "config": {
+                            "iconSize": 32
+                        },
+                        "specials": {
+                            "name": "ShoppingCartLine"
+                        }
+                    },
+                    {
+                        "type": "heading",
+                        "style": {
+                            "width": "auto",
+                            "fontSize": "20px",
+                            "fontWeight": "600",
+                            "color": "#171717",
+                            "textAlign": "center"
+                        },
+                        "specials": {
+                            "htmlTag": "h3",
+                            "text": "Your cart is empty"
+                        }
+                    },
+                    {
+                        "type": "text",
+                        "style": {
+                            "width": "auto",
+                            "fontSize": "14px",
+                            "color": "#737373",
+                            "textAlign": "center"
+                        },
+                        "specials": {
+                            "text": "Add something you like and it will show up here."
+                        }
+                    }
+                ]
+            }
+        }
+    ],
+    "quantity-dataset": [
+        {
+            "type": "quantity-button",
+            "configKey": "quantityButtonId"
+        },
+        {
+            "type": "quantity-input",
+            "configKey": "quantityInputId"
+        }
+    ],
+    "product-variants": [
+        {
+            "type": "product-variant-label",
+            "configKey": "variantLabelId"
+        },
+        {
+            "type": "product-variant-option",
+            "configKey": "variantOptionId"
+        }
+    ],
+    "dataset-block": [
+        {
+            "type": "list-empty",
+            "configKey": "emptyStateId",
+            "seed": {
+                "type": "list-empty",
+                "children": [
+                    {
+                        "type": "icon",
+                        "style": {
+                            "color": "#d4d4d4"
+                        },
+                        "config": {
+                            "iconSize": 32
+                        },
+                        "specials": {
+                            "name": "ShoppingBag3Line"
+                        }
+                    },
+                    {
+                        "type": "heading",
+                        "style": {
+                            "width": "auto",
+                            "fontSize": "20px",
+                            "fontWeight": "600",
+                            "color": "#171717",
+                            "textAlign": "center"
+                        },
+                        "specials": {
+                            "htmlTag": "h3",
+                            "text": "This item is unavailable"
+                        }
+                    },
+                    {
+                        "type": "text",
+                        "style": {
+                            "width": "auto",
+                            "fontSize": "14px",
+                            "color": "#737373",
+                            "textAlign": "center"
+                        },
+                        "specials": {
+                            "text": "It may have been removed. Have a look at the rest of the shop."
+                        }
+                    }
+                ]
+            }
+        }
+    ],
+    "list-dataset": [
+        {
+            "type": "list-empty",
+            "configKey": "emptyStateId",
+            "seedBySource": {
+                "product": {
+                    "type": "list-empty",
+                    "children": [
+                        {
+                            "type": "icon",
+                            "style": {
+                                "color": "#d4d4d4"
+                            },
+                            "config": {
+                                "iconSize": 32
+                            },
+                            "specials": {
+                                "name": "ShoppingBag3Line"
+                            }
+                        },
+                        {
+                            "type": "heading",
+                            "style": {
+                                "width": "auto",
+                                "fontSize": "20px",
+                                "fontWeight": "600",
+                                "color": "#171717",
+                                "textAlign": "center"
+                            },
+                            "specials": {
+                                "htmlTag": "h3",
+                                "text": "No products yet"
+                            }
+                        },
+                        {
+                            "type": "text",
+                            "style": {
+                                "width": "auto",
+                                "fontSize": "14px",
+                                "color": "#737373",
+                                "textAlign": "center"
+                            },
+                            "specials": {
+                                "text": "New arrivals will show up here. Check back soon."
+                            }
+                        }
+                    ]
+                },
+                "category": {
+                    "type": "list-empty",
+                    "children": [
+                        {
+                            "type": "icon",
+                            "style": {
+                                "color": "#d4d4d4"
+                            },
+                            "config": {
+                                "iconSize": 32
+                            },
+                            "specials": {
+                                "name": "ArchiveLine"
+                            }
+                        },
+                        {
+                            "type": "heading",
+                            "style": {
+                                "width": "auto",
+                                "fontSize": "20px",
+                                "fontWeight": "600",
+                                "color": "#171717",
+                                "textAlign": "center"
+                            },
+                            "specials": {
+                                "htmlTag": "h3",
+                                "text": "No collections yet"
+                            }
+                        },
+                        {
+                            "type": "text",
+                            "style": {
+                                "width": "auto",
+                                "fontSize": "14px",
+                                "color": "#737373",
+                                "textAlign": "center"
+                            },
+                            "specials": {
+                                "text": "Collections you create will show up here."
+                            }
+                        }
+                    ]
+                },
+                "article": {
+                    "type": "list-empty",
+                    "children": [
+                        {
+                            "type": "icon",
+                            "style": {
+                                "color": "#d4d4d4"
+                            },
+                            "config": {
+                                "iconSize": 32
+                            },
+                            "specials": {
+                                "name": "FileListLine"
+                            }
+                        },
+                        {
+                            "type": "heading",
+                            "style": {
+                                "width": "auto",
+                                "fontSize": "20px",
+                                "fontWeight": "600",
+                                "color": "#171717",
+                                "textAlign": "center"
+                            },
+                            "specials": {
+                                "htmlTag": "h3",
+                                "text": "No posts yet"
+                            }
+                        },
+                        {
+                            "type": "text",
+                            "style": {
+                                "width": "auto",
+                                "fontSize": "14px",
+                                "color": "#737373",
+                                "textAlign": "center"
+                            },
+                            "specials": {
+                                "text": "New stories will show up here. Check back soon."
+                            }
+                        }
+                    ]
+                },
+                "blogCategory": {
+                    "type": "list-empty",
+                    "children": [
+                        {
+                            "type": "icon",
+                            "style": {
+                                "color": "#d4d4d4"
+                            },
+                            "config": {
+                                "iconSize": 32
+                            },
+                            "specials": {
+                                "name": "InboxLine"
+                            }
+                        },
+                        {
+                            "type": "heading",
+                            "style": {
+                                "width": "auto",
+                                "fontSize": "20px",
+                                "fontWeight": "600",
+                                "color": "#171717",
+                                "textAlign": "center"
+                            },
+                            "specials": {
+                                "htmlTag": "h3",
+                                "text": "No topics yet"
+                            }
+                        },
+                        {
+                            "type": "text",
+                            "style": {
+                                "width": "auto",
+                                "fontSize": "14px",
+                                "color": "#737373",
+                                "textAlign": "center"
+                            },
+                            "specials": {
+                                "text": "Topics you create will show up here."
+                            }
+                        }
+                    ]
+                },
+                "course": {
+                    "type": "list-empty",
+                    "children": [
+                        {
+                            "type": "icon",
+                            "style": {
+                                "color": "#d4d4d4"
+                            },
+                            "config": {
+                                "iconSize": 32
+                            },
+                            "specials": {
+                                "name": "GraduationCapLine"
+                            }
+                        },
+                        {
+                            "type": "heading",
+                            "style": {
+                                "width": "auto",
+                                "fontSize": "20px",
+                                "fontWeight": "600",
+                                "color": "#171717",
+                                "textAlign": "center"
+                            },
+                            "specials": {
+                                "htmlTag": "h3",
+                                "text": "No courses yet"
+                            }
+                        },
+                        {
+                            "type": "text",
+                            "style": {
+                                "width": "auto",
+                                "fontSize": "14px",
+                                "color": "#737373",
+                                "textAlign": "center"
+                            },
+                            "specials": {
+                                "text": "Courses you publish will show up here."
+                            }
+                        }
+                    ]
+                },
+                "cart": {
+                    "type": "list-empty",
+                    "children": [
+                        {
+                            "type": "icon",
+                            "style": {
+                                "color": "#d4d4d4"
+                            },
+                            "config": {
+                                "iconSize": 32
+                            },
+                            "specials": {
+                                "name": "ShoppingCartLine"
+                            }
+                        },
+                        {
+                            "type": "heading",
+                            "style": {
+                                "width": "auto",
+                                "fontSize": "20px",
+                                "fontWeight": "600",
+                                "color": "#171717",
+                                "textAlign": "center"
+                            },
+                            "specials": {
+                                "htmlTag": "h3",
+                                "text": "Your cart is empty"
+                            }
+                        },
+                        {
+                            "type": "text",
+                            "style": {
+                                "width": "auto",
+                                "fontSize": "14px",
+                                "color": "#737373",
+                                "textAlign": "center"
+                            },
+                            "specials": {
+                                "text": "Add something you like and it will show up here."
+                            }
+                        }
+                    ]
+                },
+                "item": {
+                    "type": "list-empty",
+                    "children": [
+                        {
+                            "type": "icon",
+                            "style": {
+                                "color": "#d4d4d4"
+                            },
+                            "config": {
+                                "iconSize": 32
+                            },
+                            "specials": {
+                                "name": "ShoppingBag3Line"
+                            }
+                        },
+                        {
+                            "type": "heading",
+                            "style": {
+                                "width": "auto",
+                                "fontSize": "20px",
+                                "fontWeight": "600",
+                                "color": "#171717",
+                                "textAlign": "center"
+                            },
+                            "specials": {
+                                "htmlTag": "h3",
+                                "text": "This item is unavailable"
+                            }
+                        },
+                        {
+                            "type": "text",
+                            "style": {
+                                "width": "auto",
+                                "fontSize": "14px",
+                                "color": "#737373",
+                                "textAlign": "center"
+                            },
+                            "specials": {
+                                "text": "It may have been removed. Have a look at the rest of the shop."
+                            }
+                        }
+                    ]
+                }
+            }
+        },
+        {
+            "type": "list-loading",
+            "configKey": "loadingStateId",
+            "optional": true
+        }
+    ]
+};
+export const ELEMENT_SEEDS = {
+    "dropdown": [
+        {
+            "type": "dropdown-trigger",
+            "children": [
+                {
+                    "type": "text",
+                    "style": {
+                        "width": "fit-content"
+                    },
+                    "specials": {
+                        "text": "Dropdown"
+                    }
+                },
+                {
+                    "type": "icon",
+                    "config": {
+                        "iconSize": 16
+                    },
+                    "specials": {
+                        "name": "ArrowDownSLine"
+                    }
+                }
+            ]
+        },
+        {
+            "type": "dropdown-panel",
+            "children": [
+                {
+                    "type": "text",
+                    "style": {
+                        "padding": "6px 8px"
+                    },
+                    "specials": {
+                        "text": "Option 1"
+                    }
+                },
+                {
+                    "type": "text",
+                    "style": {
+                        "padding": "6px 8px"
+                    },
+                    "specials": {
+                        "text": "Option 2"
+                    }
+                },
+                {
+                    "type": "text",
+                    "style": {
+                        "padding": "6px 8px"
+                    },
+                    "specials": {
+                        "text": "Option 3"
+                    }
+                }
+            ]
+        }
+    ],
+    "select": [
+        {
+            "type": "dropdown-trigger"
+        },
+        {
+            "type": "dropdown-panel"
+        }
+    ],
+    "popover": [
+        {
+            "type": "dropdown-trigger",
+            "children": [
+                {
+                    "type": "text",
+                    "style": {
+                        "width": "fit-content"
+                    },
+                    "specials": {
+                        "text": "Popover"
+                    }
+                }
+            ]
+        },
+        {
+            "type": "dropdown-panel",
+            "style": {
+                "padding": "12px 16px",
+                "gap": "6px",
+                "minWidth": "240px",
+                "maxWidth": "320px"
+            },
+            "children": [
+                {
+                    "type": "heading",
+                    "style": {
+                        "fontSize": "15px"
+                    },
+                    "specials": {
+                        "htmlTag": "h4",
+                        "text": "Tiêu đề"
+                    }
+                },
+                {
+                    "type": "text",
+                    "specials": {
+                        "text": "Một câu giải thích ngắn về thứ khách vừa bấm vào."
+                    }
+                }
+            ]
+        }
+    ]
+};
+export const FIRST_CHILD_ONLY = [
+    "list-dataset"
+];

package/dist/core/tree.js

@@ -1,3 +1,4 @@
+import { SATELLITE_RULES } from '../catalog/elements.generated.js';
 /** The specials stamp a composed site overlay carries. */
 export const SPEC_OVERLAY_ID = 'overlayId';
 /** The specials stamps a composed global section carries. */
@@ -37,7 +38,26 @@ export function isOverlay(doc, id) {
 export function pageChildren(doc) {
     return childrenOf(doc, doc.root_node_id).filter((id) => !isOverlay(doc, id));
 }
-/** Depth-first walk. Cycle-safe: a malformed document must not hang a save. */
+/**
+ * Depth-first walk, children AND satellites. Cycle-safe: a malformed document
+ * must not hang a save.
+ *
+ * A satellite is a real node referenced from `config[configKey]` rather than
+ * from `data.nodes`, so a walk that follows child lists alone cannot see it. The
+ * platform states the requirement in as many words
+ * (`server/render/generated/schema_gen.go:245`): "Anything that asks 'what is
+ * inside this node?' (subtree collection, copy, delete) must consult this table
+ * as well, exactly as the editor's `subtreeIds` does."
+ *
+ * Satellite-aware is the DEFAULT, and the name stays short, for the same reason
+ * `pageChildren` has the short name and `childrenOf` the explicit one: a caller
+ * who writes the obvious thing must not be silently wrong. Copying an accordion
+ * with the child-only walk gave the copy a pointer to the ORIGINAL's skin.
+ *
+ * A `configKey` naming a node that is not in the document is skipped rather than
+ * reported here — a walk is not a validator, and a trimmed subtree is a real
+ * shape the editor handles the same way (`stores/node.ts:408-411`).
+ */
 export function walk(doc, id, visit) {
     const seen = new Set();
     const go = (cur) => {
@@ -50,6 +70,11 @@ export function walk(doc, id, visit) {
         visit(n);
         for (const k of n.data.nodes)
             go(k);
+        for (const rule of SATELLITE_RULES[n.data.type] ?? []) {
+            const sat = n.config?.[rule.configKey];
+            if (typeof sat === 'string' && sat && doc.nodes[sat])
+                go(sat);
+        }
     };
     go(id);
 }

package/dist/domains/site/builder.js

@@ -1,6 +1,7 @@
-import { isOverlay, subtreeIds, ancestors, appBlockRoot } from '../../core/tree.js';
-import { ELEMENTS } from '../../catalog/elements.generated.js';
-import { createNode } from './node.js';
+import { isOverlay, subtreeIds, ancestors, appBlockRoot, SPEC_GLOBAL_ID, SPEC_GLOBAL_KIND, SPEC_GLOBAL_REF, } from '../../core/tree.js';
+import { ELEMENTS, ELEMENT_SEEDS, SATELLITE_RULES } from '../../catalog/elements.generated.js';
+import { createNode, mintSatellites } from './node.js';
+import { refuseSecondTemplate } from './traps.js';
 import { genId } from './ids.js';
 /** Append sentinel: splice clamps a too-large index, and `isSyncablePatch`
  *  deliberately allows one — an append is a legitimate thing to describe. */
@@ -78,6 +79,7 @@ export function addSubtree(doc, parentId, spec, index) {
     refuseAppBlockParent(doc, parentId, 'adding');
     requireContainer(parent.data.type, parentId);
     requireAllowed(parent.data.type, spec.type);
+    refuseSecondTemplate(doc.doc, parentId, 'Adding');
     const patches = [];
     const ids = [];
     const build = (s, parentNodeId) => {
@@ -89,9 +91,22 @@ export function addSubtree(doc, parentId, spec, index) {
             config: s.config,
             specials: s.specials,
         });
+        // Before the owner is handed to a patch: minting rewrites its `config`.
+        const sats = mintSatellites(n);
         patches.push({ op: 'set', path: ['nodes', n.id], value: n });
         ids.push(n.id);
-        for (const child of s.children ?? []) {
+        for (const sat of sats) {
+            patches.push({ op: 'set', path: ['nodes', sat.id], value: sat });
+            ids.push(sat.id);
+        }
+        // SEEDED CONTENT, when the caller brought none of its own.
+        //
+        // `ELEMENT_SEEDS` is the content an element "is not USABLE without": a
+        // dropdown with no trigger and no panel is a bare relative box, and a select
+        // renders INTO those two nodes and draws an empty box without them. A caller
+        // who passed children has expressed an intent and is never overridden.
+        const children = s.children?.length ? s.children : (ELEMENT_SEEDS[s.type] ?? []);
+        for (const child of children) {
             requireContainer(s.type, n.id);
             requireAllowed(s.type, child.type);
             const childId = build(child, n.id);
@@ -114,6 +129,14 @@ export function addSubtree(doc, parentId, spec, index) {
  * whole subtree, and every page carrying it goes blank. That is not a
  * hypothetical — it took four pages down before this check existed.
  */
+/**
+ * The composition stamps a DUPLICATE must not inherit.
+ *
+ * `globalRev` is the fence the editor writes against a shared master
+ * (`features/globalsections/api.ts:65`); a local copy has no master and so no
+ * revision to be stale against.
+ */
+const COPY_STRIPPED_SPECIALS = [SPEC_GLOBAL_ID, SPEC_GLOBAL_REF, SPEC_GLOBAL_KIND, 'globalRev'];
 const COMPOSED_STAMPS = {
     globalId: 'globalRef',
     appBlockId: 'appBlockRef',
@@ -272,6 +295,11 @@ export function duplicateNode(doc, id) {
     if (!parentId || !doc.has(parentId)) {
         throw new Error(`sbuilder: ${id} has no parent to be duplicated beside`);
     }
+    // A copy lands BESIDE the original, so duplicating a repeater's template makes
+    // the second child the renderer will never draw. sb_add and sb_move already
+    // refuse that; duplicate is the likeliest way to reach for it, since
+    // "duplicate the card" is the move a designer makes constantly.
+    refuseSecondTemplate(doc.doc, parentId, 'Duplicating into');
     const patches = [];
     const ids = [];
     // One pass, parent-first, so a child's `parent` always names an id already
@@ -281,12 +309,44 @@ export function duplicateNode(doc, id) {
         const clone = JSON.parse(JSON.stringify(src));
         clone.id = genId(src.data.type);
         clone.data = { ...clone.data, parent: newParent, nodes: [] };
+        // A COPY IS NOT THE SHARED MASTER.
+        //
+        // The stamps came over verbatim, so duplicating a global header produced two
+        // ROOT children carrying one globalId — ErrDuplicateGlobal
+        // (server/internal/page/decompose.go:293), refused on a LATER save, by which
+        // time the agent has kept editing and reads it as a transport error. Strip
+        // rather than refuse: unlike an overlay or an app block, whose copies the
+        // SERVER would destroy, a stripped global copy is a perfectly valid
+        // document, and it is what a designer means by duplicating a header to make
+        // a variant.
+        for (const stamp of COPY_STRIPPED_SPECIALS)
+            delete clone.specials?.[stamp];
         patches.push({ op: 'set', path: ['nodes', clone.id], value: clone });
         ids.push(clone.id);
         for (const kid of src.data.nodes) {
             const kidId = copy(kid, clone.id);
             patches.push({ op: 'insert', path: ['nodes', clone.id, 'data', 'nodes'], index: APPEND, value: kidId });
         }
+        // SATELLITES, deep-copied with the owner's pointer rewritten — the editor's
+        // copyNode does exactly this (`editor/src/stores/node.ts:373,403`). Without
+        // it the copy pointed at the ORIGINAL's skin: editing one changed both, and
+        // removing the original deleted the skin out from under the copy.
+        //
+        // Written as an explicit patch rather than by mutating `clone` after it has
+        // been handed to one, so the emitted patch list says what it does.
+        for (const rule of SATELLITE_RULES[src.data.type] ?? []) {
+            const satId = src.config?.[rule.configKey];
+            const path = ['nodes', clone.id, 'config', rule.configKey];
+            if (typeof satId === 'string' && satId && doc.has(satId)) {
+                patches.push({ op: 'set', path, value: copy(satId, clone.id) });
+            }
+            else if (satId !== undefined) {
+                // A satellite id that resolves to nothing is a trimmed subtree, which the
+                // editor handles the same way (`stores/node.ts:408-411`). Carrying the
+                // pointer would aim the copy at a node it does not own.
+                patches.push({ op: 'unset', path });
+            }
+        }
         return clone.id;
     };
     const rootId = copy(id, parentId);
@@ -317,6 +377,10 @@ export function moveNode(doc, id, newParentId, index) {
     }
     requireContainer(newParent.data.type, newParentId);
     requireAllowed(newParent.data.type, n.data.type);
+    // Not for a REORDER: a node already in this parent is not a second template,
+    // and refusing it would block the one move that is always safe.
+    if (n.data.parent !== newParentId)
+        refuseSecondTemplate(doc.doc, newParentId, 'Moving');
     const patches = [];
     const oldParentId = n.data.parent;
     if (oldParentId && doc.has(oldParentId)) {

package/dist/domains/site/findings.js

@@ -25,6 +25,13 @@ export const FIX = {
         'sb_remove id "<id>". Setting "<key>" on this one would show the same value in every row.',
     unbound_dataset_element: 'Bind it: sb_bind id "<id>", field "specials.<key>", and the source that names the record ' +
         'field you want (sb_bind refuses an unknown source and lists every valid one).',
+    unlinked_form: 'Point it at a real form: sb_set id "<id>", namespace specials, keys ' +
+        '{ "formId": "<a form id from sb_api_find \'list forms\'>" }.',
+    dead_menu_link: 'Write the entries the renderer actually reads: sb_set id "<id>", namespace specials, keys ' +
+        '{ "menuItems": [{ "id": "mi-1", "label": "Shop", "href": "/shop" }] }. Setting menuId alone ' +
+        'publishes an empty nav — the Go renderer never reads it.',
+    extra_repeater_child: 'Keep one template: sb_remove the extra children of "<id>", or sb_move them out. Design the ' +
+        'single remaining child — it is what every record is drawn with.',
     dead_binding_source: `Rebind with sb_bind using one of: ${BINDING_SOURCES.join(', ')}.`,
     // "<key>" here is documentation, not a placeholder: this template is never
     // filled with a key, so the reader sees the form a field must take.
@@ -58,3 +65,54 @@ export function compactFindings(items) {
     });
     return { findings, fixes };
 }
+/**
+ * What a COMPOSE WARNING means for the document now in hand.
+ *
+ * These ride on `GET .../source` beside the page. The client typed the field and
+ * read it nowhere, which mattered most for the one that is destructive:
+ * `globalMissing` means the server could not find the master and DELETED the
+ * reference node from the tree it handed back (`compose.go:118,127`), so the
+ * page opens with the section already gone and the next save stores that loss
+ * permanently — with no error at any step.
+ */
+export const COMPOSE_WARNINGS = {
+    globalMissing: 'The shared section is GONE from the tree you just opened — the server could not find its ' +
+        'master and removed the reference. Saving from here makes that permanent. Re-add the section, ' +
+        'or restore the master, before you save.',
+    globalStale: 'A shared section was edited elsewhere while this copy was held; the master write was refused.',
+    overlayStale: 'The overlay master was edited elsewhere while this copy was held; that write was refused. ' +
+        'The page edits in the same request were kept.',
+    appBlockMissing: 'An app block on this page no longer resolves; its subtree composed as nothing.',
+    appBlockEdited: 'An edit inside an app block was reduced back to its reference on save, and is stored nowhere.',
+    formMissing: 'A form placement names a form that no longer exists, so it publishes as an EMPTY BOX rather ' +
+        'than an error.',
+};
+/**
+ * Turn the server's warnings into something a reader can act on.
+ *
+ * The two id fields are separate on the wire on purpose — they name rows in
+ * different tables, and one field holding "an id of whichever kind the code
+ * implies" is the shape that makes a client resolve it against the wrong store.
+ * An unknown code is passed through rather than dropped: a warning this build
+ * has never heard of is still the platform telling the caller something.
+ */
+export function composeWarnings(raw) {
+    if (!raw?.length)
+        return [];
+    const out = [];
+    for (const w of raw) {
+        if (!w || typeof w !== 'object')
+            continue;
+        const { code, globalId, overlayId, name } = w;
+        if (typeof code !== 'string' || !code)
+            continue;
+        const id = typeof overlayId === 'string' && overlayId ? overlayId : globalId;
+        out.push({
+            code,
+            ...(typeof id === 'string' && id ? { id } : {}),
+            ...(typeof name === 'string' && name ? { name } : {}),
+            effect: COMPOSE_WARNINGS[code] ?? 'The platform reported this about the page it composed.',
+        });
+    }
+    return out;
+}

package/dist/domains/site/node.js

@@ -1,4 +1,4 @@
-import { ELEMENTS } from '../../catalog/elements.generated.js';
+import { ELEMENTS, SATELLITE_RULES } from '../../catalog/elements.generated.js';
 import { genId } from './ids.js';
 /** Structured clone via JSON — the defaults are plain data, and this is what
  *  stops two nodes of the same type sharing one nested object. */
@@ -57,3 +57,92 @@ export function createNode(type, opts = {}) {
         bindings: copy(d.bindings ?? []),
     };
 }
+/**
+ * Mint the SATELLITES a freshly created node owns, and point it at them.
+ *
+ * A satellite is a real node in the document's node map referenced from
+ * `config[configKey]` instead of `data.nodes` — a style-holder like the tab's
+ * shared button skin. The editor's node store mints them the moment an element
+ * is added (`editor/src/element/seeds.ts:5-7`, `stores/node.ts` addDetachedNode)
+ * and this server did not, so an accordion it created carried no
+ * `accordionItemId` at all. A missing satellite "simply resolves to nothing at
+ * assemble time and the renderer takes its degrade path"
+ * (`server/render/scope/capture.go:98-105`) — for a repeater that means ghost
+ * cards shown to a shopper, which the platform's own meta calls a lie.
+ *
+ * MUTATES `owner.config`, so call it before the owner is handed to a patch, and
+ * only on a node this process just created.
+ *
+ * An `optional` rule is skipped deliberately: `list-loading` is the one opt-in
+ * satellite in the platform, because a list with no loading design shows a
+ * silhouette of its own cards, which is the better answer for almost every site.
+ * A `configKey` the caller already filled is left alone — an explicit id beats a
+ * minted one.
+ */
+export function mintSatellites(owner, seen = new Set()) {
+    // A type is expanded once per call chain. No element owns itself today, and a
+    // future one that did would otherwise mint until the stack ran out.
+    if (seen.has(owner.data.type))
+        return [];
+    seen.add(owner.data.type);
+    const out = [];
+    for (const rule of SATELLITE_RULES[owner.data.type] ?? []) {
+        if (rule.optional)
+            continue;
+        const existing = owner.config[rule.configKey];
+        if (typeof existing === 'string' && existing)
+            continue;
+        // A satellite is usually one bare skin node, but the three list-empty
+        // owners are born as a SUBTREE — the editor calls addDetachedTree for them,
+        // and a bare list-empty is blank space where it shows a glyph, a headline
+        // and a line of body.
+        const seed = seedFor(rule, owner);
+        const born = seed
+            ? buildFromSeed(seed, owner.id, seen)
+            : [createNode(rule.type, { parent: owner.id })];
+        owner.config[rule.configKey] = born[0].id;
+        out.push(...born, ...(seed ? [] : mintSatellites(born[0], seen)));
+    }
+    return out;
+}
+/**
+ * Which seed subtree this satellite is born as, if any.
+ *
+ * A repeater's empty state says "No products yet" or "No posts yet" depending on
+ * what it lists, so the table is keyed by the owner's `config.datasetSource`.
+ * An unknown source falls back to `product`, exactly as the editor's `copyFor`
+ * does — a list whose source this build does not know still gets a designed
+ * empty state rather than a blank one.
+ */
+function seedFor(rule, owner) {
+    if (rule.seed)
+        return rule.seed;
+    if (!rule.seedBySource)
+        return undefined;
+    const src = owner.config.datasetSource;
+    const key = typeof src === 'string' ? src : 'product';
+    return rule.seedBySource[key] ?? rule.seedBySource.product;
+}
+/**
+ * Mint a whole seeded subtree, ROOT FIRST.
+ *
+ * Root-first matters to every caller: the owner points `config[configKey]` at
+ * `[0]`, and `addSubtree` links a child by the same index. Each node is created
+ * through `createNode`, so it still gets its element's own defaults and
+ * bindings; the seed carries only what the seed decided.
+ */
+export function buildFromSeed(seed, parent, seen) {
+    const n = createNode(seed.type, {
+        parent,
+        style: seed.style,
+        config: seed.config,
+        specials: seed.specials,
+    });
+    const out = [n, ...mintSatellites(n, seen ? new Set(seen) : undefined)];
+    for (const child of seed.children ?? []) {
+        const kids = buildFromSeed(child, n.id, seen);
+        n.data.nodes.push(kids[0].id);
+        out.push(...kids);
+    }
+    return out;
+}

package/dist/domains/site/review.js

@@ -1,5 +1,5 @@
 import { childrenOf, isOverlay, pageChildren, appBlockRoot } from '../../core/tree.js';
-import { ELEMENTS, BINDING_SOURCES, BOUND_SPECIALS } from '../../catalog/elements.generated.js';
+import { ELEMENTS, BINDING_SOURCES, BOUND_SPECIALS, FIRST_CHILD_ONLY } from '../../catalog/elements.generated.js';
 import { fill } from './findings.js';
 /**
  * Shipped with every non-empty finding list.
@@ -175,6 +175,72 @@ export function reviewDesign(doc) {
                 });
             }
         }
+        // A FORM NOBODY LINKED publishes as an empty box, and the platform stays
+        // deliberately quiet about it: form.go:221 skips an empty formId with the
+        // comment that reporting it "would cry wolf on every page mid-edit". True
+        // for a human mid-drag, wrong for an agent that has finished — and since the
+        // element seeds `formId: ""` and forms compose on the RENDER path only, the
+        // canvas looks identical either way. An unlinked form is the DEFAULT.
+        if (type === 'form') {
+            const formId = (n.specials ?? {}).formId;
+            if (typeof formId !== 'string' || formId.trim() === '') {
+                out.push({
+                    code: 'unlinked_form',
+                    nodeId: id,
+                    type,
+                    problem: 'This form names no form, so it composes nothing and publishes as an empty box — ' +
+                        'and the platform reports no warning for it.',
+                    key: 'formId',
+                    fix: fill('unlinked_form', { id, key: 'formId' }),
+                });
+            }
+        }
+        // A MENU ENTRY WITH NO HREF is a link that goes nowhere. The Go renderer
+        // reads specials.menuItems and never menuId, so picking a menu by id
+        // publishes an empty nav, and the element's own seed ships one entry
+        // ("Home") whose href is "". Resolution from a menu id to real addresses is
+        // client-side (editor/src/features/menus/snapshot.ts), so nothing fills it
+        // in on the way to publish.
+        if (type === 'menu') {
+            const items = (n.specials ?? {}).menuItems;
+            const rows = Array.isArray(items) ? items : [];
+            const dead = rows.filter((r) => {
+                const row = (r ?? {});
+                const href = row.href;
+                const panel = row.panelId;
+                return ((typeof href !== 'string' || href.trim() === '') &&
+                    (typeof panel !== 'string' || panel.trim() === ''));
+            });
+            if (rows.length === 0 || dead.length > 0) {
+                out.push({
+                    code: 'dead_menu_link',
+                    nodeId: id,
+                    type,
+                    problem: rows.length === 0
+                        ? 'This menu has no entries, so it publishes as an empty nav. The renderer reads ' +
+                            'specials.menuItems and never menuId.'
+                        : `${dead.length} of ${rows.length} entries have no href, so those links go ` +
+                            'nowhere. The renderer reads specials.menuItems and never menuId.',
+                    key: 'menuItems',
+                    fix: fill('dead_menu_link', { id, key: 'menuItems' }),
+                });
+            }
+        }
+        // A REPEATER RENDERS ITS FIRST CHILD AND DROPS THE REST. `templateID`
+        // returns Data.Nodes[0], and list-dataset is the only renderer that does —
+        // which is why the list is generated rather than derived from the obvious
+        // "is a dataset container" predicate, since dataset-block renders all of
+        // its children.
+        if (FIRST_CHILD_ONLY.includes(type) && n.data.nodes.length > 1) {
+            out.push({
+                code: 'extra_repeater_child',
+                nodeId: id,
+                type,
+                problem: `"${type}" clones only its FIRST child per record, so the other ` +
+                    `${n.data.nodes.length - 1} never appear on the published page.`,
+                fix: fill('extra_repeater_child', { id }),
+            });
+        }
         // A dataset element with NO binding at all is the same silence from the other
         // direction: its renderer is waiting for a bound special that nothing writes,
         // so it falls back to whatever the document authored — once, for every record.

package/dist/domains/site/traps.js

@@ -1,3 +1,4 @@
+import { FIRST_CHILD_ONLY } from '../../catalog/elements.generated.js';
 import { pageChildren, isOverlay, SPEC_GLOBAL_ID, SPEC_GLOBAL_KIND, } from '../../core/tree.js';
 /**
  * Which band a direct child of ROOT belongs to.
@@ -95,4 +96,27 @@ export const RESPONSIVE_NOTICE = 'Written per breakpoint, which is the default b
     'legitimate too — it is the cascade\'s fallback layer, below every breakpoint slot, and ' +
     'where an element\'s own defaults live. Use base for a value that genuinely should not ' +
     'vary; use a breakpoint for anything a narrower screen should change.';
+/**
+ * Refuse a child a repeater would never render.
+ *
+ * `list-dataset` clones `Data.Nodes[0]` per record and ignores every sibling
+ * after it (`server/render/nodes/list-dataset/html.go:60`). A second child is a
+ * perfectly valid document: it stores, it publishes, and it simply never appears
+ * — so the agent designs a card nobody will ever see and nothing says why.
+ *
+ * The list is GENERATED from the renderers. `dataset-block` is a dataset
+ * container too and renders all of its children, so the obvious
+ * `isContainer && category === 'dataset'` predicate would have restricted the
+ * wrong element.
+ */
+export function refuseSecondTemplate(doc, parentId, verb) {
+    const parent = doc.nodes[parentId];
+    if (!parent || !FIRST_CHILD_ONLY.includes(parent.data.type))
+        return;
+    if (parent.data.nodes.length === 0)
+        return;
+    throw new Error(`sbuilder: "${parent.data.type}" (${parentId}) renders only its FIRST child, once per ` +
+        `record — Data.Nodes[0] is the template. ${verb} a second one stores fine and never ` +
+        'appears on the published page. Design the existing template, or sb_remove it first.');
+}
 export { isOverlay };

package/dist/domains/site/validate.js

@@ -1,4 +1,4 @@
-import { subtreeIds } from '../../core/tree.js';
+import { subtreeIds, childrenOf, SPEC_GLOBAL_ID, SPEC_OVERLAY_ID, } from '../../core/tree.js';
 import { checkBandOrder } from './traps.js';
 /**
  * Everything that would make the platform refuse this document on save.
@@ -16,6 +16,36 @@ export function validateForSave(doc) {
     const band = checkBandOrder(d);
     if (band)
         problems.push(band);
+    // COMPOSITION STAMPS: only a DIRECT child of ROOT may carry one, and never the
+    // same id twice.
+    //
+    // The platform refuses both — ErrGlobalNested / ErrDuplicateGlobal
+    // (server/internal/page/decompose.go:256,293) and their overlay twins
+    // (overlay.go:46-55). It refuses them LATE, though: the agent keeps editing
+    // and one autosave later gets a bare `duplicate_global`, which reads like a
+    // transport error rather than something it did. The overlay pair is worse
+    // still — it has no mapped error code and falls through to writeErr's default.
+    const rootKids = new Set(childrenOf(d, d.root_node_id));
+    for (const stamp of [SPEC_GLOBAL_ID, SPEC_OVERLAY_ID]) {
+        const seen = new Map();
+        for (const [id, n] of Object.entries(d.nodes)) {
+            const value = n.specials?.[stamp];
+            if (typeof value !== 'string' || !value)
+                continue;
+            if (!rootKids.has(id)) {
+                problems.push(`Node ${id} carries ${stamp} "${value}" but is not a direct child of ROOT. ` +
+                    'The platform refuses the save; move it to ROOT or remove the stamp.');
+                continue;
+            }
+            const first = seen.get(value);
+            if (first) {
+                problems.push(`Nodes ${first} and ${id} both carry ${stamp} "${value}". One page may reference ` +
+                    'it only once — remove one, or drop the stamp to make it a plain local section.');
+                continue;
+            }
+            seen.set(value, id);
+        }
+    }
     // Dangling child ids: a parent naming a node that is not in the map. The
     // renderer walks children by id, so this is a hole in the rendered page.
     for (const [id, n] of Object.entries(d.nodes)) {

package/dist/smoke.js

@@ -98,6 +98,35 @@ export async function runSmoke() {
     doc.apply(add2(doc, 'rt', { type: 'flex-section', children: [{ type: 'text' }] }).patches);
     const codes = reviewDesign(doc).map((f) => f.code);
     check('an unfilled placeholder IS reported', codes.includes('placeholder_content'));
+    // A REPEATER ARRIVES WITH ITS EMPTY STATE.
+    //
+    // On its OWN document, because a repeater with no card template is a genuinely
+    // empty container and would answer the review check below with a finding it is
+    // right to make.
+    //
+    // The satellite hangs off `config.emptyStateId`, not the child list, so every
+    // walk that follows children only reports this document as correct while the
+    // renderer takes its degrade path and ships ghost cards to a shopper.
+    const satDoc = PageDoc.from({
+        schema_version: 2,
+        root_node_id: 'rt',
+        nodes: {
+            rt: {
+                id: 'rt',
+                data: { type: 'root', parent: null, nodes: [], isCanvas: true, hidden: false, custom: {} },
+                style: {}, config: {}, specials: {}, responsive: {}, events: [], bindings: [],
+            },
+        },
+    });
+    const satSection = addSubtree(satDoc, 'rt', { type: 'flex-section' });
+    satDoc.apply(satSection.patches);
+    const listed = addSubtree(satDoc, satSection.ids[0], { type: 'list-dataset' });
+    satDoc.apply(listed.patches);
+    const list = satDoc.node(listed.ids[0]);
+    const emptyId = list.config.emptyStateId;
+    check('a repeater is minted with its empty state', typeof emptyId === 'string' && satDoc.has(emptyId) && satDoc.node(emptyId).data.type === 'list-empty');
+    check('the empty state carries its design, not a blank box', satDoc.node(String(emptyId)).data.nodes.length === 3);
+    check('a document carrying satellites still stores', validateForSave(satDoc).length === 0);
     console.error('ALL GOOD');
 }
 runSmoke().catch((err) => {

package/dist/tools/page.js

@@ -1,9 +1,10 @@
 import { z } from 'zod';
+import { composeWarnings } from '../domains/site/findings.js';
 import { text } from '../mcp/response.js';
 import { loadSource, saveSource } from '../transport/pages.js';
 import { PageDoc } from '../domains/site/document.js';
 import { addSubtree, setMany, moveNode, removeNode, duplicateNode, } from '../domains/site/builder.js';
-import { request } from '../transport/http.js';
+import { request, redact } from '../transport/http.js';
 import { siteToken } from './credentialpick.js';
 import { validateForSave } from '../domains/site/validate.js';
 import { reviewDesign, REVIEW_NOTICE } from '../domains/site/review.js';
@@ -42,6 +43,7 @@ export class PageSession {
     pageId = '';
     live = null;
     stale = null;
+    warnings = [];
     boxes = [];
     constructor(ctx) {
         this.ctx = ctx;
@@ -90,8 +92,15 @@ export class PageSession {
         this.doc = PageDoc.from(src.document);
         this.siteId = siteId;
         this.pageId = pageId;
+        // The platform's own account of what it could not compose. Typed on the
+        // response since the transport was written and read by nothing until now.
+        this.warnings = composeWarnings(src.warnings);
         return this.doc.outline();
     }
+    /** What the server said it could not compose when this page was opened. */
+    composeWarnings() {
+        return this.warnings;
+    }
     current() {
         if (!this.doc)
             throw new Error('sbuilder: no page is open — call sb_page_open first');
@@ -151,9 +160,11 @@ export function registerPageTools(server, ctx) {
                 'the renderer finds no root and publishes an EMPTY BODY. The next save from here writes ' +
                 'the canonical key and fixes it; publish afterwards.'
             : undefined;
+        const warnings = session.composeWarnings();
         return text({
             outline,
             ...(blank_page_repair ? { blank_page_repair } : {}),
+            ...(warnings.length ? { compose_warnings: warnings } : {}),
             ...reviewField(ctx, doc),
         });
     });
@@ -423,9 +434,12 @@ export function registerPageTools(server, ctx) {
             ...(is_homepage !== undefined ? { isHomepage: is_homepage } : {}),
             ...(settings ? { settings } : {}),
         };
+        // `settings` is the one free-form object a caller hands this server, so the
+        // preview and the echo both go through redact — everything else on this
+        // path is built from narrow arguments.
         if (dry_run !== false)
-            return text({ dry_run: true, would_post: path, body });
-        return text(await request({
+            return text({ dry_run: true, would_post: path, body: redact(body) });
+        const res = redact(await request({
             base: ctx.base,
             method: 'POST',
             path,
@@ -433,6 +447,24 @@ export function registerPageTools(server, ctx) {
             body,
             fetchImpl: ctx.fetchImpl,
         }));
+        // A COLLIDING SLUG IS RENAMED, NOT REFUSED. `uniqueSlug` suffixes -1, -2 …
+        // and its own comment says it "never errors"
+        // (server/internal/page/service.go:877). ErrSlugConflict exists and maps to
+        // 409; this path never reaches it. So the create answers 200 carrying a
+        // DIFFERENT slug than the one asked for, and every link the caller then
+        // authors to the slug it requested is dead.
+        const got = res.page?.slug;
+        const renamed = slug && typeof got === 'string' && got !== slug;
+        return text({
+            ...res,
+            ...(renamed
+                ? {
+                    slug_renamed: `The slug "${slug}" was already taken, so the platform stored ` +
+                        `"${got}" instead and reported success. Link to "${got}", or free the name and ` +
+                        'create it again.',
+                }
+                : {}),
+        });
     });
     server.registerTool('sb_publish', {
         description: 'Compile the draft into the live page. PUBLISH CASCADES: a page sharing a global ' +
@@ -451,7 +483,7 @@ export function registerPageTools(server, ctx) {
         const body = { pageIds: [page_id] };
         if (dry_run !== false)
             return text({ dry_run: true, would_post: path, body });
-        return text(await request({
+        const res = (await request({
             base: ctx.base,
             method: 'POST',
             path,
@@ -459,6 +491,31 @@ export function registerPageTools(server, ctx) {
             body,
             fetchImpl: ctx.fetchImpl,
         }));
+        // A PUBLISHED ROW CARRIES THE WHOLE RENDERED PAGE — document, html and css
+        // — and publish CASCADES, so returning the response as it arrives pours
+        // every republished page's markup into the reader. Kept: what identifies
+        // the row and what a caller would act on.
+        const published = (res.published ?? []).map((p) => ({
+            pageId: p.pageId,
+            ...(p.slug !== undefined ? { slug: p.slug } : {}),
+            ...(p.isHomepage ? { isHomepage: true } : {}),
+        }));
+        // PUBLISH SKIPS A PAGE WITH NO SAVED DRAFT and still answers 200 with
+        // whatever did publish (`server/internal/page/service.go:650`, a bare
+        // `continue`). sb_page_create followed by sb_publish does exactly that:
+        // the call succeeds, the page never flips to published, and the URL 404s.
+        const landed = published.some((p) => p.pageId === page_id);
+        return text({
+            published,
+            ...(published.length !== (res.total ?? published.length) ? { total: res.total } : {}),
+            ...(landed
+                ? {}
+                : {
+                    not_published: `Page ${page_id} has no saved draft, so the platform published ` +
+                        'nothing for it and reported success anyway. Open it with sb_page_open, save an ' +
+                        'edit, then publish again.',
+                }),
+        });
     });
     return session;
 }

package/dist/transport/http.js

@@ -34,8 +34,10 @@ const SECRET_KEYS = /^(authorization|token|access_?token|refresh_?token|password
 /**
  * Replace credential-shaped values with a marker, recursively.
  *
- * Every dry-run preview goes through this, so it is the only thing standing
- * between a `dry_run` result and a bearer token sitting in a transcript. It keys
+ * Every preview that can carry a FREE-FORM object goes through this — `sb_api_call`'s
+ * body and `sb_page_create`'s `settings`, the two places a caller supplies a shape
+ * this server does not type. The rest of the dry-run previews echo patch counts or
+ * bodies built from narrow arguments, which cannot hold a credential. It keys
  * off the FIELD NAME rather than the value's shape on purpose: a token format
  * can change tomorrow, while the field name is what this repo controls.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbuilder-mcp",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "MCP server that designs and operates a Store Builder site — pages, data, theme and publish — through the platform's own API and live-edit protocol.",
   "mcpName": "io.github.vuluu2k/sbuilder-mcp",
   "type": "module",