sbuilder-mcp 0.4.4 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,23 @@ 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.5.0] - 2026-09-08
+
+### Added
+- sb_review reports default_seed_copy when a satellite's empty state still carries the platform's own English seed text, such as a repeater's empty state saying "No products yet", which previously matched no rule and reviewed clean.
+- sb_review reports form_fields_flush when a form, form-segment or form-step-nav stacks its fields with no gap between them, so each label reads as belonging to the control above it.
+- The install CLI accepts --site-name, matching the flag the platform's own Agent app install line already appends; it rides in as SB_SITE_NAME alongside the site id, and sb_connect reports it back so a session can display the store's name instead of its id.
+- A dry run of the install CLI now reports its own preview outcome and exit code instead of reusing the failure marker and exit code of a real install.
+- sb_api_call now falls back {siteId} and {siteID} path parameters to SB_SITE across all 289 operations that name the site, matching the fallback every other tool already applies through siteFor(); an explicit argument still wins.
+
+### Fixed
+- sb_set's state parameter now writes to the location the platform's cascade actually reads: node.states[state] at base, node.responsive[breakpoint].states[state] per breakpoint. Previously it wrote to a path nothing reads, and base:true combined with state:"hover" wrote the hover value straight into the plain style, leaving a node permanently styled as if hovered with no hover state at all.
+- sb_set now refuses a state argument on specials instead of silently dropping it, since content and identity do not vary by interaction state.
+- sb_review now walks into satellite nodes (a repeater's empty state, a variant option's skin, a quantity stepper's buttons, a menu or tab item's skin), so findings inside them are reported instead of being invisible to every check.
+- sb_review and sb_set now report a site-wide edit as such: a change to a node inside a global section's interior, or inside a site overlay like the cart drawer, is flagged rather than reading as an ordinary page-local edit.
+- sb_look now opens a closed overlay (such as the cart drawer) before measuring it, so a node_id resolving inside one can be photographed at all instead of failing with a clipping error that named neither the overlay nor the reason.
+- sb_look's preview_note no longer claims the draft preview renders every repeater's empty state; the draft preview threads real store data just like a published page, and the note now describes the real caveat, which is that an entity template previews with nothing bound.
+
 ## [0.4.4] - 2026-09-08
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,23 @@ 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.5.0] - 2026-09-08
+
+### Added
+- sb_review giờ báo cáo default_seed_copy khi một node vệ tinh ở trạng thái rỗng vẫn còn mang seed text tiếng Anh của nền tảng, chẳng hạn trạng thái rỗng của một repeater ghi "No products yet" — trước đây không khớp với rule nào nên review vẫn báo sạch.
+- sb_review giờ báo cáo form_fields_flush khi một form, form-segment hoặc form-step-nav xếp các field mà không có gap, khiến mỗi label đọc như thể thuộc về control phía trên nó.
+- CLI cài đặt giờ nhận --site-name, khớp với flag mà dòng lệnh cài đặt của chính Agent app trên nền tảng đã thêm vào; giá trị này đi kèm dưới dạng SB_SITE_NAME cùng với site id, và sb_connect báo cáo lại giá trị này để một session có thể hiển thị tên cửa hàng thay vì id.
+- Một dry run của CLI cài đặt giờ báo cáo kết quả xem trước và exit code riêng, thay vì dùng chung dấu hiệu thất bại và exit code của một lần cài đặt thật.
+- sb_api_call giờ fallback các path parameter {siteId} và {siteID} về SB_SITE trên toàn bộ 289 operation có tên site, khớp với cách fallback mà mọi tool khác đã áp dụng qua siteFor(); một tham số được truyền rõ ràng vẫn được ưu tiên.
+
+### Fixed
+- Tham số state của sb_set giờ ghi đúng vào vị trí mà cascade của nền tảng thực sự đọc: node.states[state] ở base, node.responsive[breakpoint].states[state] theo từng breakpoint. Trước đây nó ghi vào một đường dẫn không ai đọc, và base:true kết hợp với state:"hover" ghi thẳng giá trị hover vào style thường, khiến node mang màu hover vĩnh viễn mà không hề có trạng thái hover.
+- sb_set giờ từ chối tham số state trên specials thay vì âm thầm bỏ qua, vì nội dung và identity không thay đổi theo trạng thái tương tác.
+- sb_review giờ đi vào cả các node vệ tinh (trạng thái rỗng của repeater, skin của một variant option, các nút của quantity stepper, skin của một mục menu hoặc tab), nên các finding bên trong chúng được báo cáo thay vì vô hình với mọi check.
+- sb_review và sb_set giờ báo cáo một chỉnh sửa có phạm vi toàn site đúng như bản chất của nó: thay đổi một node bên trong phần thân của một global section, hoặc bên trong một overlay của site như cart drawer, giờ được gắn cờ thay vì đọc như một chỉnh sửa cục bộ trên trang.
+- sb_look giờ mở một overlay đang đóng (như cart drawer) trước khi đo, nên một node_id nằm bên trong overlay đó giờ có thể được chụp ảnh, thay vì thất bại với lỗi clip không nêu rõ overlay hay lý do.
+- preview_note của sb_look không còn khẳng định rằng bản xem trước bản nháp render trạng thái rỗng của mọi repeater; bản xem trước bản nháp truyền dữ liệu cửa hàng thật giống như một trang đã publish, và ghi chú giờ mô tả đúng lưu ý thực sự — đó là một entity template xem trước sẽ không có gì được bind.
+
 ## [0.4.4] - 2026-09-08
 
 ### Added

package/README.md

@@ -23,6 +23,11 @@ worse than one that does not exist.
 as `SB_SITE` and every tool then defaults to it. Without it the model has to carry the id
 through the session, which it can only get by listing pages and reading one back.
 
+`--site-name "Your Store"` rides alongside it as `SB_SITE_NAME`. It is a label, never an
+address — nothing resolves by it — but it lets the agent say the store's name back to you
+instead of a 32-character id you did not choose. The **Apps → AI agent** screen appends it
+whenever the store has a name.
+
 It **merges**: the servers already in those files stay, whatever it replaces is copied to
 `<file>.sbuilder-backup`, and a config it cannot parse is refused rather than overwritten —
 a file with a trailing comma is far likelier than one worth discarding, and it is what you

package/README.vi.md

@@ -23,6 +23,11 @@ còn tệ hơn một cờ không tồn tại.
 thành `SB_SITE` và mọi tool sau đó mặc định dùng site đó. Không có nó thì model phải mang
 theo id suốt phiên, mà cách duy nhất để lấy là liệt kê trang rồi đọc ngược ra.
 
+`--site-name "Tên Cửa Hàng"` đi kèm, được ghi thành `SB_SITE_NAME`. Nó là một nhãn, không phải
+địa chỉ — không có gì phân giải theo nó — nhưng nhờ nó agent gọi được tên cửa hàng thay vì
+đọc lại một id 32 ký tự bạn không đặt. Màn hình **Apps → AI agent** tự thêm nó khi cửa hàng
+có tên.
+
 Nó **gộp**: các server đã có trong file được giữ nguyên, thứ nó thay thế được chép sang
 `<file>.sbuilder-backup`, và một config nó không đọc được thì bị từ chối chứ không ghi đè —
 một file thừa dấu phẩy khả dĩ hơn nhiều một file đáng vứt, và đó chính là thứ bạn cần để sửa.

package/dist/catalog/checkout.generated.js

@@ -759,7 +759,8 @@ export const CHECKOUT_PAGE_DOCUMENT = {
                 "display": "flex",
                 "flexDirection": "column",
                 "width": "100%",
-                "height": "fit-content"
+                "height": "fit-content",
+                "gap": "12px"
             },
             "config": {},
             "specials": {

package/dist/catalog/elements.generated.js

@@ -5834,7 +5834,8 @@ export const ELEMENTS = {
                 "display": "flex",
                 "flexDirection": "column",
                 "width": "100%",
-                "height": "fit-content"
+                "height": "fit-content",
+                "gap": "12px"
             }
         },
         "inspector": [

package/dist/core/tree.js

@@ -87,6 +87,32 @@ export function walk(doc, id, visit) {
     };
     go(id);
 }
+/**
+ * One level of `walk`: `data.nodes` followed by the satellites on `config[key]`.
+ *
+ * For a caller that needs its OWN recursion — carrying scope down as it goes,
+ * the way `reviewDesign` carries "am I inside a repeater / an overlay" — and so
+ * cannot hand the traversal to `walk`. Such a caller reaching for `childrenOf`
+ * is the mistake `walk`'s comment warns about, and `sb_review` made it: it never
+ * saw a satellite, so every empty state, every variant-option skin and every
+ * quantity stepper was outside the review entirely.
+ *
+ * Satellites come AFTER the real children and are not deduplicated against
+ * them — a `configKey` pointing at a node that is also a child would be a
+ * malformed document, and a walk is not a validator.
+ */
+export function childrenWithSatellites(doc, id) {
+    const n = doc.nodes[id];
+    if (!n)
+        return [];
+    const out = [...n.data.nodes];
+    for (const rule of SATELLITE_RULES[n.data.type] ?? []) {
+        const sat = n.config?.[rule.configKey];
+        if (typeof sat === 'string' && sat && doc.nodes[sat])
+            out.push(sat);
+    }
+    return out;
+}
 export function subtreeIds(doc, id) {
     const out = [];
     walk(doc, id, (n) => out.push(n.id));
@@ -114,6 +140,26 @@ export function ancestors(doc, id) {
  * therefore stored nowhere and reported nowhere — trap 5. Nearest stamp wins:
  * the block root answers with itself.
  */
+/**
+ * The site overlay this node sits in, or null. Nearest stamp wins, so the
+ * overlay root answers with itself.
+ *
+ * `isOverlay` answers only for the ROOT of one, which is right for the rules
+ * that decide whether a node may BE an overlay. It is the wrong question for a
+ * WRITE: an edit to a node inside the cart drawer is an edit to the drawer, and
+ * the drawer is one master shared by every page on the site. Without this, a
+ * `sb_set` on a drawer node reported a plain page-local success while changing
+ * ten pages — the same asymmetry `sb_review` closed when it started walking
+ * overlays and flagging their findings `overlay: true`.
+ */
+export function overlayRoot(doc, id) {
+    if (isOverlay(doc, id))
+        return id;
+    for (const a of ancestors(doc, id))
+        if (isOverlay(doc, a))
+            return a;
+    return null;
+}
 export function appBlockRoot(doc, id) {
     const stamped = (n) => n !== undefined &&
         (n.specials?.[SPEC_APP_BLOCK_ID] !== undefined || n.specials?.[SPEC_APP_BLOCK_REF] !== undefined);

package/dist/domains/site/builder.js

@@ -182,12 +182,42 @@ export function setKeys(doc, id, keys, opts) {
     const rebind = namespace === 'config' ? rebindPatch(doc, id, keys) : null;
     if (namespace === 'specials') {
         refuseComposedStamp(keys);
+        // `specials` is content and identity, base-only by definition, and states
+        // carry style. Saying so is the point: this used to drop the state and write
+        // the value as if it had been asked for plainly.
+        if (opts.state) {
+            throw new Error(`sbuilder: specials takes no interaction state — "${opts.state}" would be dropped. ` +
+                'specials is content and identity (text, htmlTag, bound…), which do not vary by ' +
+                'state. Style is what has states.');
+        }
         return Object.entries(keys).map(([k, v]) => ({
             op: 'set',
             path: ['nodes', id, 'specials', k],
             value: v,
         }));
     }
+    // A STATE IS ANSWERED BEFORE `base`, because `base` used to be tested first
+    // and swallowed it: `base:true state:"hover"` wrote the hover value straight
+    // into the plain style, so the node wore its hover colour permanently and had
+    // no hover at all. The tool reported success, and this repo's own design skill
+    // documents that exact call — `sb_set pr_option style base:true state:"active"`
+    // — as the way to style a selected option.
+    if (opts.state) {
+        // Base state and per-breakpoint state are DIFFERENT PLACES in the document,
+        // and the old path (`states[state][bp][ns]`) was neither of them: it buried
+        // a breakpoint inside the base-state cluster, where nothing reads it.
+        const prefix = opts.base
+            ? ['nodes', id, 'states', opts.state]
+            : ['nodes', id, 'responsive', opts.breakpoint ?? 'desktop', 'states', opts.state];
+        return [
+            ...Object.entries(keys).map(([k, v]) => ({
+                op: 'set',
+                path: [...prefix, namespace, k],
+                value: v,
+            })),
+            ...(rebind ? [rebind] : []),
+        ];
+    }
     if (opts.base) {
         // Base IS legitimate, and this used to throw for anything that was not an
         // identity key — a refusal built on a misread of the platform's responsive
@@ -217,16 +247,6 @@ export function setKeys(doc, id, keys, opts) {
         ];
     }
     const bp = opts.breakpoint ?? 'desktop';
-    if (opts.state) {
-        return [
-            ...Object.entries(keys).map(([k, v]) => ({
-                op: 'set',
-                path: ['nodes', id, 'states', opts.state, bp, namespace, k],
-                value: v,
-            })),
-            ...(rebind ? [rebind] : []),
-        ];
-    }
     return [
         ...Object.entries(keys).map(([k, v]) => ({
             op: 'set',

package/dist/domains/site/findings.js

@@ -18,6 +18,15 @@ export const FIX = {
     empty_text: 'Set it: sb_set id "<id>", namespace specials, keys { "<key>": … }.',
     missing_media: 'Set it: sb_set id "<id>", namespace specials, keys { "<key>": … }.',
     placeholder_content: 'Write the real copy: sb_set id "<id>", namespace specials, keys { "<key>": … }.',
+    // Named apart from placeholder_content because the reader needs telling that
+    // this surface EXISTS. An empty state is authored out of sight — it only shows
+    // when the list is empty — so an agent that never saw it does not know there is
+    // anything to write.
+    default_seed_copy: 'Write it in the shop\'s own language and ink: sb_set id "<id>", namespace specials, ' +
+        'keys { "<key>": … }. It is a seeded satellite (an empty state, an element\'s chrome), ' +
+        'so it only appears when the list is empty or the control is idle — sb_outline lists it ' +
+        'under its owner as satellite:"<config key>". Style it too: the seed ships #171717 ink ' +
+        'and #d4d4d4 icons, which are the platform\'s, not the site\'s.',
     // The fix is a DIFFERENT ELEMENT, not a value: setting "<key>" here would put
     // one authored value on every row of the repeater.
     static_in_dataset: `Swap the element: sb_add one of ${RECORD_ELEMENTS} in the same parent, sb_bind it ` +
@@ -25,6 +34,12 @@ 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).',
+    // The value the platform now seeds on these elements, so a repair matches what
+    // a freshly created form would have.
+    form_fields_flush: 'Give the stack room: sb_set id "<id>", namespace style, base true, keys { "gap": "12px" } ' +
+        '— the value the platform seeds on form / form-segment / form-step-nav. Raise it if the ' +
+        'design wants more air; it must stay clear of config.fieldStackGap, which is the smaller ' +
+        'label-to-control gap INSIDE one field.',
     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 ' +

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, FIRST_CHILD_ONLY } from '../../catalog/elements.generated.js';
+import { childrenOf, childrenWithSatellites, isOverlay, pageChildren, appBlockRoot } from '../../core/tree.js';
+import { ELEMENTS, BINDING_SOURCES, BOUND_SPECIALS, FIRST_CHILD_ONLY, SATELLITE_RULES, ELEMENT_SEEDS } from '../../catalog/elements.generated.js';
 import { fill } from './findings.js';
 /**
  * Shipped with every non-empty finding list.
@@ -23,6 +23,57 @@ function contentKeys(type) {
 function seededValue(type, key) {
     return (ELEMENTS[type]?.defaults.specials ?? {})[key];
 }
+/**
+ * Every line of copy the PLATFORM writes into a seeded subtree.
+ *
+ * `placeholder_content` above compares against `ELEMENTS[type].defaults.specials`
+ * — the element's OWN default — and that is exactly why it could never see an
+ * empty state. A heading's own default is `"Heading"`; the heading inside a
+ * repeater's empty state is minted from `SATELLITE_RULES`' seed tree and says
+ * `"No products yet"`. Different source, so the check walked straight past it.
+ *
+ * The consequence was general, not incidental: EVERY store built with these
+ * tools ships the platform's English empty states and reviews clean. Measured on
+ * a Vietnamese storefront — home, category, product and search all reported
+ * "nothing a visitor would notice" while four repeaters said "No products yet"
+ * and "New arrivals will show up here. Check back soon." in `#171717` on a page
+ * that is `#2E2A3B` throughout. It is the most-visited copy on a store: an empty
+ * cart is the empty state a shopper meets first.
+ *
+ * Collected from BOTH generated seed tables, so a new empty state the platform
+ * ships is covered by the next `npm run codegen` rather than by an edit here.
+ */
+const SEEDED_SUBTREE_TEXT = (() => {
+    const out = new Set();
+    const visit = (v) => {
+        if (Array.isArray(v)) {
+            for (const x of v)
+                visit(x);
+            return;
+        }
+        if (v === null || typeof v !== 'object')
+            return;
+        const o = v;
+        const t = o.specials?.text;
+        if (typeof t === 'string' && t.trim() !== '')
+            out.add(t);
+        for (const x of Object.values(v))
+            visit(x);
+    };
+    visit(SATELLITE_RULES);
+    visit(ELEMENT_SEEDS);
+    return out;
+})();
+/**
+ * The containers whose children are form FIELDS.
+ *
+ * Named rather than derived: "offers a Gap control" is true of 33 elements and
+ * four of them legitimately seed none (`flex-section` and `flex-block` are the
+ * layout primitives, where the author composes the spacing). What makes these
+ * three different is that their children are LABELLED CONTROLS, and a label with
+ * no space above it attaches itself to the wrong one.
+ */
+const FIELD_STACKS = new Set(['form', 'form-segment', 'form-step-nav']);
 /**
  * A container that renders its subtree ONCE PER RECORD.
  *
@@ -111,7 +162,13 @@ export function reviewDesign(doc) {
         if (appBlockRoot(d, id) === id)
             return;
         const inner = repeats(d.nodes[id]?.data.type ?? '') ? (repeater ?? id) : repeater;
-        for (const k of childrenOf(d, id))
+        // SATELLITES INCLUDED. `childrenOf` here meant the review never entered one,
+        // so an element's whole chrome — every repeater's empty state, the variant
+        // option skin, the quantity stepper, the menu and tab item skins — sat
+        // outside the check that exists to say what a visitor meets. `walk`'s own
+        // comment names this as the mistake a caller makes by reaching for the
+        // child-only list; this had made it.
+        for (const k of childrenWithSatellites(d, id))
             go(k, inner, overlay || overlayIds.has(k));
     };
     go(d.root_node_id);
@@ -212,6 +269,22 @@ export function reviewDesign(doc) {
                     fix: fill('placeholder_content', { id, key }),
                 });
             }
+            // The same defect, one seed table over — see SEEDED_SUBTREE_TEXT. Reported
+            // separately because the FIX reads differently: this copy is not a
+            // "<Heading>" nobody noticed, it is a real English sentence that renders
+            // as if somebody meant it.
+            else if (key === 'text' && typeof value === 'string' && SEEDED_SUBTREE_TEXT.has(value)) {
+                out.push({
+                    code: 'default_seed_copy',
+                    nodeId: id,
+                    type,
+                    problem: `Still the platform's own seed copy (${JSON.stringify(value)}), in English. This ` +
+                        'surface was never authored — it is minted with the element and reads as if ' +
+                        'somebody wrote it.',
+                    key,
+                    fix: fill('default_seed_copy', { id, key }),
+                });
+            }
         }
         // 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
@@ -233,6 +306,42 @@ export function reviewDesign(doc) {
                 });
             }
         }
+        // A FORM WHOSE FIELDS TOUCH. The three field stacks lay out `display:flex`
+        // + `flexDirection:column`, so with no `gap` every field sits flush against
+        // the one above it and each label ends up nearer the previous control than
+        // its own — the one thing a form's spacing has to get right.
+        //
+        // Measured on a published checkout at 1440px: six consecutive fields, every
+        // gap between them EXACTLY 0. The platform now seeds `gap: 12px` on these
+        // elements, but `defaults` seeds at CREATION, so every form authored before
+        // that keeps the spacing it was given and nothing says so.
+        //
+        // NOT a child check: a form's fields live in the FORM DOCUMENT and are
+        // composed on the render path, so the page's own node has `nodes: []` and
+        // counting children would report every form as empty.
+        if (FIELD_STACKS.has(type)) {
+            const slots = [
+                n.style,
+                ...Object.values(n.responsive ?? {}).map((s) => s?.style),
+            ];
+            const anyGap = slots.some((s) => {
+                const g = s?.gap;
+                return g !== undefined && g !== null && `${g}`.trim() !== '' && parseFloat(`${g}`) > 0;
+            });
+            if (!anyGap) {
+                out.push({
+                    code: 'form_fields_flush',
+                    nodeId: id,
+                    type,
+                    problem: 'This form stacks its fields with no gap, so each one touches the one above it and ' +
+                        "every label reads as belonging to the control above rather than its own. The " +
+                        'field\'s own label-to-control spacing (config.fieldStackGap) is a different, ' +
+                        'smaller quantity and does not close this.',
+                    key: 'gap',
+                    fix: fill('form_fields_flush', { id, key: 'gap' }),
+                });
+            }
+        }
         // 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

package/dist/domains/site/traps.js

@@ -1,5 +1,5 @@
 import { FIRST_CHILD_ONLY } from '../../catalog/elements.generated.js';
-import { pageChildren, isOverlay, SPEC_GLOBAL_ID, SPEC_GLOBAL_KIND, SPEC_GLOBAL_REV, SPEC_OVERLAY_ID, SPEC_OVERLAY_REV, } from '../../core/tree.js';
+import { pageChildren, isOverlay, overlayRoot, ancestors, SPEC_GLOBAL_ID, SPEC_GLOBAL_KIND, SPEC_GLOBAL_REV, SPEC_OVERLAY_ID, SPEC_OVERLAY_REV, } from '../../core/tree.js';
 /**
  * Which band a direct child of ROOT belongs to.
  *
@@ -60,6 +60,22 @@ export function checkBandOrder(doc) {
 export function isGlobal(doc, id) {
     return doc.nodes[id]?.specials?.[SPEC_GLOBAL_ID] !== undefined;
 }
+/**
+ * The global section this node sits in, or null. Nearest stamp wins.
+ *
+ * `isGlobal` answers for the stamped ROOT alone, which is the right question for
+ * "may this node be moved out of the band it is in". It is the wrong one for a
+ * WRITE: nobody restyles the header section, they restyle a button inside it,
+ * and that edit is just as site-wide.
+ */
+export function globalRoot(doc, id) {
+    if (isGlobal(doc, id))
+        return id;
+    for (const a of ancestors(doc, id))
+        if (isGlobal(doc, a))
+            return a;
+    return null;
+}
 /**
  * The sentence to attach to any result that touched a global.
  *
@@ -69,10 +85,32 @@ export function isGlobal(doc, id) {
  * not know this reports "updated the header" having changed the whole site.
  */
 export function globalWarning(doc, id) {
-    if (!isGlobal(doc, id))
-        return null;
-    const gid = doc.nodes[id].specials[SPEC_GLOBAL_ID];
-    return `Node ${id} is the shared global section ${JSON.stringify(gid)}. Editing it changes EVERY page that carries it, and publishing cascades to all of them. Say so when reporting this change.`;
+    // THE STAMP IS ON THE SECTION ROOT, and asking only `isGlobal(id)` meant the
+    // warning fired for the one node nobody edits. The work happens INSIDE: a nav
+    // button in the global header, a line of the global footer. Restyling
+    // `bu_…` changed all ten pages of a site and the result said nothing, while
+    // the same edit one level up would have warned. Same asymmetry as the overlay
+    // one below, one construct over.
+    const g = globalRoot(doc, id);
+    if (g !== null) {
+        const gid = doc.nodes[g].specials?.[SPEC_GLOBAL_ID];
+        const kind = doc.nodes[g].specials?.[SPEC_GLOBAL_KIND];
+        const self = g === id ? '' : ` (inside global ${g})`;
+        return `Node ${id}${self} belongs to the shared global section ${JSON.stringify(gid)}${kind ? ` (${kind})` : ''}. Editing it changes EVERY page that carries it, and publishing cascades to all of them. Say so when reporting this change.`;
+    }
+    // AN OVERLAY IS SHARED TOO, and this used to answer only for globals. The cart
+    // drawer and the pop-ups are ONE master composed onto every page, so an edit
+    // to a node inside one is site-wide — measured: restyling the drawer's
+    // quantity stepper touched ten pages and the result read as a page-local
+    // success. It is the write-side of the reason `sb_review` flags overlay
+    // findings `overlay: true` instead of reporting them once per page.
+    const ov = overlayRoot(doc, id);
+    if (ov !== null) {
+        const oid = doc.nodes[ov].specials?.[SPEC_OVERLAY_ID];
+        const self = ov === id ? '' : ` (inside overlay ${ov})`;
+        return `Node ${id}${self} belongs to the site overlay ${JSON.stringify(oid)} — the cart drawer or a pop-up. It is ONE master composed onto every page, so this change is site-wide, not page-local. Say so when reporting it.`;
+    }
+    return null;
 }
 /**
  * Keys that are identity or content rather than a visual quantity.

package/dist/install/index.js

@@ -9,11 +9,21 @@ export const SERVER_NAME = 'sbuilder';
  * at a real install, read by nothing, and reported as success — the caller then
  * spent the session wondering why the site was not selected. A flag that is
  * silently dropped is worse than one that does not exist.
+ *
+ * BUT REFUSING ONE THE PLATFORM ITSELF EMITS IS WORSE STILL, and that is what
+ * `--site-name` became. The editor's Agent app builds the whole install line for
+ * the merchant to paste — `AgentAppPanel.vue`, which appends
+ * `--site-name "<store>"` whenever it knows the name, with a test pinning it —
+ * so the ONE documented install path exited 1 and installed nothing. The flag
+ * was never noise; it was added on the platform side after this list was
+ * written. It is a label, not a credential: it rides in as SB_SITE_NAME so the
+ * agent can say "Áo Thun" instead of reading back site_14675b5a570b248d.
  */
 const FLAGS = [
     '--token',
     '--api',
     '--site',
+    '--site-name',
     '--email',
     '--password',
     '--client',
@@ -30,6 +40,11 @@ export function buildEntry(opts, pkg = 'sbuilder-mcp') {
     // model the guess it otherwise makes from a page list.
     if (opts.site)
         env.SB_SITE = opts.site;
+    // The name the merchant calls the store, so the agent can too. Carried only
+    // alongside an id — a name with nothing to resolve to is decoration, and a
+    // second install would file it under a site it does not name.
+    if (opts.site && opts.siteName)
+        env.SB_SITE_NAME = opts.siteName;
     // Only when a key is absent: a key opens everything the agent does day to day,
     // and writing an account password into six config files to buy the handful of
     // account-level calls it adds is a bad trade the installer should not make for
@@ -109,6 +124,7 @@ export function runInstallCli(argv) {
         token: get('--token') ?? process.env.SB_TOKEN,
         api: get('--api') ?? process.env.SB_API,
         site: get('--site') ?? process.env.SB_SITE,
+        siteName: get('--site-name') ?? process.env.SB_SITE_NAME,
         email: get('--email') ?? process.env.SB_EMAIL,
         password: get('--password') ?? process.env.SB_PASSWORD,
         clients: get('--client')?.split(','),
@@ -134,7 +150,17 @@ export function runInstallCli(argv) {
         return 1;
     }
     for (const r of results) {
-        const mark = r.status === 'installed' ? '✔' : r.status === 'unchanged' ? '·' : '✖';
+        // A DRY RUN THAT WROTE NOTHING DID ITS JOB. Every line used to be marked
+        // `✖` and the command exited 1, so the one way to inspect an install before
+        // making it reported total failure — and a CI step wrapping it would stop
+        // there. The preview gets its own mark and its own exit code.
+        const mark = opts.dryRun
+            ? '→'
+            : r.status === 'installed'
+                ? '✔'
+                : r.status === 'unchanged'
+                    ? '·'
+                    : '✖';
         console.error(`${mark} ${r.client} — ${r.status}${r.reason ? ` (${r.reason})` : ''}`);
         console.error(`    ${r.path}`);
         // The undo, named. A config writer that changes a file without saying where
@@ -144,5 +170,7 @@ export function runInstallCli(argv) {
         if (r.note)
             console.error(`    ${r.note}`);
     }
+    if (opts.dryRun)
+        return 0;
     return results.some((r) => r.status === 'installed' || r.status === 'unchanged') ? 0 : 1;
 }

package/dist/server.js

@@ -49,6 +49,7 @@ export function buildContext() {
         session: new Session(base),
         apiKey: process.env.SB_TOKEN,
         siteId: process.env.SB_SITE,
+        siteName: process.env.SB_SITE_NAME,
         notices: new Notices(), undo: new UndoLog(),
     };
 }

package/dist/tools/api.js

@@ -163,6 +163,14 @@ export function tokenFor(ctx, credential) {
     }
     return undefined;
 }
+/**
+ * The path parameters that mean "THIS site" — lowercased, because the platform
+ * writes `{siteId}` in 281 operations and `{siteID}` in 8.
+ *
+ * Deliberately only the site. `{productId}`, `{id}` and the rest name a record
+ * the caller chose; the site is the one id an install already holds.
+ */
+const SITE_PARAMS = new Set(['siteid']);
 export async function callOperation(ctx, args) {
     const op = API_OPERATIONS.find((o) => o.id === args.id);
     if (!op)
@@ -185,6 +193,16 @@ export async function callOperation(ctx, args) {
             if (folded !== undefined)
                 value = given[folded];
         }
+        // SB_SITE ANSWERS FOR {siteId}, exactly as it does for every tool's
+        // `site_id` argument through `siteFor()`. It did not here, and this is the
+        // surface where it costs most: `sb_api_call` reaches 484 operations and 289
+        // of them name the site, so a key-only install — where the id is a constant
+        // the environment already holds — made the model carry a 32-character
+        // string through every raw call it made. An explicit argument still wins,
+        // so a session spanning two sites works by naming each.
+        if (value === undefined && SITE_PARAMS.has(name.toLowerCase()) && ctx.siteId) {
+            value = ctx.siteId;
+        }
         if (value === undefined) {
             // NAME THE ARGUMENT, not just the parameter. The call sheet lists these
             // under `params` while the call takes them in `path_params`, and a caller

package/dist/tools/live.js

@@ -24,7 +24,7 @@ const DATASET_TYPES = new Set([
 import { RealtimeSocket } from '../transport/socket.js';
 import { LiveSession } from '../live/session.js';
 import { refuseAppBlockInterior } from '../domains/site/builder.js';
-import { childrenOf, isOverlay, subtreeIds } from '../core/tree.js';
+import { childrenOf, isOverlay, overlayRoot, subtreeIds } from '../core/tree.js';
 import { siteToken } from './credentialpick.js';
 import { siteFor } from './context.js';
 import { projectList, MEDIA_FIELDS } from './project.js';
@@ -275,7 +275,21 @@ export function registerLiveTools(server, ctx, session) {
         // the process; `shoot` keeps them in `widths` order. The format changes
         // bytes and latency only — the client prices an image by its pixel size,
         // so jpeg and png cost the agent the same tokens.
-        const shots = await shoot(target, { widths: widths ?? DEFAULT_WIDTHS, node: node_id, format });
+        // FRAMING A NODE IN THE CART DRAWER MEANS OPENING THE DRAWER. A closed
+        // overlay is translated off-screen, so the clip lands outside the image
+        // and the shot fails with a Playwright error naming neither the overlay
+        // nor the reason. `overlayRoot` answers for a node ANYWHERE inside one,
+        // which is the case that matters: the caller frames the stepper or the
+        // empty state, not the drawer root.
+        const openOverlay = node_id
+            ? (overlayRoot(session.current().doc, node_id) ?? undefined)
+            : undefined;
+        const shots = await shoot(target, {
+            widths: widths ?? DEFAULT_WIDTHS,
+            node: node_id,
+            format,
+            ...(openOverlay ? { open: openOverlay } : {}),
+        });
         // The boxes feed the presence cursor as well as the agent's own reading.
         session.noteBoxes(shots[0]?.boxes ?? []);
         // The findings ride WITH the picture. Judging a page by eye and judging it
@@ -301,10 +315,30 @@ export function registerLiveTools(server, ctx, session) {
         // Say it ONCE, and only when it can actually mislead: a page with no
         // store-driven element has nothing to be missing from the preview.
         const dataDriven = Object.values(session.current().doc.nodes).some((n) => DATASET_TYPES.has(n.data.type));
+        // THIS NOTE USED TO SAY THE OPPOSITE, and it sent readers to fix a page
+        // that was right. It claimed the draft preview "threads no store data:
+        // every repeater renders its empty state there" — measured false: a home
+        // page previewed four real products at their real prices, matching the
+        // catalogue exactly. `ServePreview` runs RenderDraft → gather → assemble,
+        // the SAME path as a published page, and the platform's own comment on it
+        // says the result is "byte-identical to what publishing this source would
+        // serve" (storefront.go:1260). The shoot path's own comment had already
+        // recorded the observation — "identical content on screen (images, prices,
+        // no empty states)" — while this note contradicted it.
+        //
+        // What the preview genuinely cannot do is resolve ONE RECORD from the URL:
+        // ServePreview never runs entity routing (that lives in ServeHost), so an
+        // entity TEMPLATE previews with nothing bound. That is the real caveat,
+        // and it is the opposite population of pages from the one the old note
+        // warned about.
         const previewNote = !url && dataDriven
-            ? ctx.notices.once('preview-scope', 'This is the DRAFT PREVIEW, which threads no store data: every repeater renders its ' +
-                'empty state there, however correct the page is. Publish and pass the storefront ' +
-                'URL as `url` to see real products.')
+            ? ctx.notices.once('preview-scope', 'This is the DRAFT PREVIEW. It renders through the same path as a published page, ' +
+                'so repeaters DO show real store records — judge a list page from it. What it ' +
+                'cannot do is resolve a single record from the address: on an ENTITY TEMPLATE ' +
+                '(the product or category detail page) nothing is bound, so the title is blank, ' +
+                'the price reads zero and a variant picker shows the element\'s seed options ' +
+                '("Color / Size", "Red / S") rather than the product\'s own. That is the preview, ' +
+                'not the page. Pass a published storefront URL as `url` to judge a template.')
             : undefined;
         return images(shots.map((s) => ({ dataBase64: s.imageBase64, mimeType: s.mimeType })), {
             widths: shots.map((s) => s.width),

package/dist/tools/session.js

@@ -24,9 +24,10 @@ export async function connect(ctx, args) {
             sites: [],
             api_key: 'present',
             ...(ctx.siteId ? { site: ctx.siteId } : {}),
+            ...(ctx.siteId && ctx.siteName ? { site_name: ctx.siteName } : {}),
             operations: API_OPERATIONS.length,
             note: ctx.siteId
-                ? `Connected with an API key alone, on site ${ctx.siteId} (SB_SITE). Every tool ` +
+                ? `Connected with an API key alone, on site ${ctx.siteId} (SB_SITE)${ctx.siteName ? `, the store called ${JSON.stringify(ctx.siteName)}` : ''}. Every tool ` +
                     'defaults to it, so site_id is optional. Set SB_EMAIL and SB_PASSWORD as well if ' +
                     'you want account-level calls (listing sites, members, roles), which a key cannot make.'
                 : 'Connected with an API key alone. It is bound to one site, so there is no site list — ' +

package/dist/vision/shoot.js

@@ -243,6 +243,30 @@ async function shootOne(page, url, width, format, opts) {
     // storefront. The settle is best-effort: if the page does go quiet, the shot
     // waits for it; if it never does, the shot happens anyway.
     await page.goto(url, { waitUntil: 'load', timeout: 30_000 });
+    // OPEN THE OVERLAY BEFORE MEASURING, or it cannot be photographed at all.
+    //
+    // A closed drawer is `visibility:hidden` and translated 105% off-screen
+    // (`render/nodes/cart-drawer/css.go`), so it measures at x=1461 on a 1440
+    // viewport and `page.screenshot({clip})` fails outright: "Clipped area is
+    // either empty or outside the resulting image". That made the ONE surface this
+    // repo's own guidance insists you look at — "open the cart drawer and look,
+    // before calling a site done" — the one surface `sb_look` could not show.
+    //
+    // `is-open` is the platform's OWN mechanism, not a hack around it: the same
+    // class the storefront's cart button toggles, whose rule is `transform:none`
+    // plus `visibility:visible`. The scrim takes it too, so the shot matches what
+    // a shopper sees rather than a panel floating over bare page.
+    if (opts.open) {
+        await page.evaluate((id) => {
+            // The narrow `document` shim this file declares is for the MEASUREMENT
+            // pass; here the real DOM is what runs, so reach it through the cast
+            // rather than widening a shim that exists to keep that pass honest.
+            const d = document;
+            d.getElementById(id)?.classList.add('is-open');
+            for (const s of d.querySelectorAll('.wb-cart-scrim'))
+                s.classList.add('is-open');
+        }, opts.open);
+    }
     await settleDom(page);
     await settleLazyImages(page);
     // A RENDERED page carries its node ids as the HTML `id` attribute — not as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbuilder-mcp",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "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",