sbuilder-mcp 0.46.3 → 0.47.1

package/CHANGELOG.md

@@ -6,6 +6,24 @@ 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.47.1] - 2026-09-14
+
+### Fixed
+- `sb_page_create` with `is_homepage` set on a site that already has one no longer creates a duplicate that steals the star and leaves the platform's own original home page reachable at no address; it now adopts the existing home page instead, renaming it when the caller named it something else, and reports what it did instead of creating anything.
+
+## [0.47.0] - 2026-09-14
+
+### Added
+- `sb_api_find`'s call sheet now names a `summary_covers` list whenever the platform wrote one sentence for several routes at once, so a call sheet is no longer read as if its summary belongs to that route alone; `sb_api_find` adds a one-time directive pointing at the sharpest case, `/refund` versus `/refund-via-gateway`, where reading the shared sentence would record a refund that never pays anybody.
+- `sb_api_find` and `sb_api_call` no longer inline a request body definition for a GET or DELETE operation whenever the document's declared body is a verbatim copy of a write operation's, naming the route it was copied from instead of describing a body the route cannot take.
+- `sb_api_find` and `sb_api_call` now list every path parameter a route actually needs, even when the document's own `@Param` list omits it, so a caller no longer has to make a failing call first to discover an argument the sheet never mentioned.
+- The catalog's legal-value vocabulary grows to cover 18 more elements read directly off the platform's own declarations, including `popup`'s trigger frequency and close position, `tab`'s alignment, `menu`'s expand type and submenu style, `theme-switcher` and `locale-switcher`'s variants, `chat-widget`'s corner, `cart-drawer` and `hamburger-menu`'s slide-in edge, and a new "Product viewer" mode on `spline-scene` for drag-to-turn, pinch-to-zoom inspection of a 3D model.
+
+### Fixed
+- Duplicate `@Param` entries copied onto an operation by a shared doc comment no longer appear more than once in `sb_api_find`'s call sheet.
+- `image-comparison`'s `splitDirection` config key is no longer reported as a dead key, because the platform itself has dropped the seed rather than leaving it unread.
+- The catalog's fallback note for a config or specials value now credits the renderer that actually normalises an unrecognised value, instead of crediting a platform vocabulary declaration that defines the legal words but says nothing about what happens to any other one.
+
 ## [0.46.3] - 2026-09-14
 
 ### Fixed

package/CHANGELOG.vi.md

@@ -6,6 +6,24 @@ 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.47.1] - 2026-09-14
+
+### Fixed
+- `sb_page_create` với `is_homepage` được bật trên một site đã có sẵn trang chủ giờ không còn tạo ra một trang trùng lặp cướp mất ngôi sao và khiến trang chủ gốc của nền tảng trở nên không thể truy cập ở bất kỳ địa chỉ nào; giờ nó nhận lại trang chủ hiện có, đổi tên nếu người gọi đặt tên khác, và báo cáo việc đã làm thay vì tạo trang mới.
+
+## [0.47.0] - 2026-09-14
+
+### Added
+- Call sheet của `sb_api_find` giờ nêu danh sách `summary_covers` mỗi khi nền tảng viết chung một câu mô tả cho nhiều route, nhờ đó một call sheet không còn bị đọc như thể câu mô tả đó chỉ dành riêng cho route ấy; `sb_api_find` thêm một chỉ dẫn phát một lần trỏ đến trường hợp gay gắt nhất, `/refund` so với `/refund-via-gateway`, nơi đọc theo câu mô tả dùng chung sẽ ghi nhận một khoản hoàn tiền mà không ai thực sự nhận được.
+- `sb_api_find` và `sb_api_call` không còn chèn nguyên định nghĩa request body cho một operation GET hoặc DELETE mỗi khi body được khai báo trong tài liệu là bản sao y nguyên của một operation ghi dữ liệu, mà thay vào đó nêu tên route đã bị sao chép từ đó thay vì mô tả một body mà route này không thể nhận.
+- `sb_api_find` và `sb_api_call` giờ liệt kê đầy đủ mọi path parameter mà một route thực sự cần, kể cả khi danh sách `@Param` của tài liệu bỏ sót nó, nhờ đó người gọi không còn phải thử gọi thất bại trước mới phát hiện ra một đối số mà call sheet chưa từng nhắc tới.
+- Bảng giá trị hợp lệ của catalog mở rộng để bao phủ thêm 18 phần tử, đọc trực tiếp từ các khai báo của chính nền tảng, gồm tần suất kích hoạt và vị trí nút đóng của `popup`, căn chỉnh của `tab`, kiểu mở rộng và kiểu submenu của `menu`, biến thể của `theme-switcher` và `locale-switcher`, góc đặt của `chat-widget`, cạnh trượt ra của `cart-drawer` và `hamburger-menu`, cùng một chế độ mới "Product viewer" trên `spline-scene` cho phép kéo để xoay, chụm để phóng to khi xem một mô hình 3D.
+
+### Fixed
+- Các mục `@Param` bị trùng do một đoạn chú thích tài liệu dùng chung sao chép vào một operation giờ không còn xuất hiện nhiều lần trong call sheet của `sb_api_find`.
+- Config key `splitDirection` của `image-comparison` không còn bị báo là dead key, vì chính nền tảng đã bỏ luôn giá trị seed đó thay vì để nó không ai đọc tới.
+- Ghi chú fallback của catalog cho một giá trị config hoặc specials giờ ghi công cho đúng renderer thực sự chuẩn hóa một giá trị không nhận diện được, thay vì ghi công cho một khai báo bảng giá trị của nền tảng — vốn chỉ định nghĩa các từ hợp lệ chứ không nói gì về việc điều gì xảy ra với một từ khác.
+
 ## [0.46.3] - 2026-09-14
 
 ### Fixed

package/dist/catalog/deadkeys.generated.js

@@ -1,8 +1,8 @@
 export const DEAD_KEY_SOURCE = {
-    "files": 3966,
-    "identifiers": 76235,
+    "files": 3974,
+    "identifiers": 76582,
     "seededKeys": 384,
-    "dead": 1
+    "dead": 0
 };
 /**
  * Keys an element SEEDS and no renderer anywhere reads.
@@ -16,14 +16,4 @@ export const DEAD_KEY_SOURCE = {
  * because the platform accepts the value and a refusal here would invent a rule
  * it does not have.
  */
-export const DEAD_KEYS = {
-    "splitDirection": {
-        "key": "splitDirection",
-        "namespaces": [
-            "config"
-        ],
-        "seededBy": [
-            "image-comparison"
-        ]
-    }
-};
+export const DEAD_KEYS = {};

package/dist/catalog/elements.generated.js

@@ -3832,7 +3832,8 @@ export const ELEMENTS = {
                 "modelUrl": "",
                 "posterUrl": "",
                 "sceneControls": [],
-                "sceneGallery": "podium"
+                "sceneGallery": "podium",
+                "sceneViewer": "off"
             },
             "style": {
                 "width": "100%",
@@ -3899,6 +3900,13 @@ export const ELEMENTS = {
                             "scene_model"
                         ]
                     },
+                    {
+                        "key": "scene_viewer",
+                        "label": "Product viewer",
+                        "controls": [
+                            "scene_viewer"
+                        ]
+                    },
                     {
                         "key": "scene_display",
                         "label": "Display",
@@ -3966,6 +3974,7 @@ export const ELEMENTS = {
             "scene_effect",
             "scene_gallery",
             "scene_model",
+            "scene_viewer",
             "scene_display",
             "scene_controls",
             "border",
@@ -3993,7 +4002,8 @@ export const ELEMENTS = {
             "Effect: four shaders (gradient mesh, floating particles, waves, aurora) with speed, intensity and a grain toggle. Its colours follow the site theme until you switch them to custom",
             "Spline: paste the link from Spline — Export → Viewer → copy link (…/scene.splinecode)",
             "Add a poster image so the box is not blank while a Spline scene loads; an effect draws immediately and needs none",
-            "Scene controls (rotate on scroll, tilt with the mouse) drive named objects, so they apply to a Spline scene and not to an effect, which has no objects"
+            "Scene controls (rotate on scroll, tilt with the mouse) drive named objects, so they apply to a Spline scene and not to an effect, which has no objects",
+            "For letting a shopper INSPECT a product, turn on Product viewer instead of building scene controls — it is drag to turn, wheel or pinch to zoom, and a slow idle spin, and it works on a phone where the mouse triggers do not. It is offered on the built-in scenes and on your own model, and it replaces the scene controls rather than joining them: both move the same object"
         ],
         "semantics": [
             "3d",
@@ -9777,7 +9787,6 @@ export const ELEMENTS = {
                 "afterSize": "cover",
                 "afterPosition": "center center",
                 "splitPosition": 50,
-                "splitDirection": "horizontal",
                 "imageRatio": "auto"
             }
         },
@@ -36916,6 +36925,24 @@ export const ELEMENT_VALUES = {
             ],
             "fallback": "",
             "readBy": "nodes/popup/html.go:triggerType"
+        },
+        "triggerFreq": {
+            "target": "config",
+            "writeKey": "triggerFreq",
+            "values": [
+                "always",
+                "once"
+            ],
+            "readBy": "POPUP_TRIGGER_FREQS (VOCAB in schema/src/elements/popup/meta.ts)"
+        },
+        "closePos": {
+            "target": "config",
+            "writeKey": "closePos",
+            "values": [
+                "inside",
+                "outside"
+            ],
+            "readBy": "POPUP_CLOSE_POSITIONS (VOCAB in schema/src/elements/popup/meta.ts)"
         }
     },
     "pricing-dataset": {
@@ -36944,6 +36971,15 @@ export const ELEMENT_VALUES = {
             "open": true,
             "readBy": "nodes/product-image-feature/css.go:featureRatioCss"
         },
+        "featureClickAction": {
+            "target": "config",
+            "writeKey": "featureClickAction",
+            "values": [
+                "open_gallery",
+                "open_product_page"
+            ],
+            "readBy": "FEATURE_CLICK_ACTIONS (VOCAB in schema/src/elements/product-image-feature/meta.ts)"
+        },
         "main_image_source": {
             "target": "config",
             "writeKey": "mainImageSource",
@@ -36964,11 +37000,49 @@ export const ELEMENT_VALUES = {
                 "right",
                 "top"
             ],
+            "readBy": "TAB_POSITIONS (VOCAB in schema/src/elements/tab/meta.ts)",
             "fallback": "top",
-            "readBy": "nodes/tab/html.go:position"
+            "fallbackReadBy": "nodes/tab/html.go:position"
+        },
+        "tabAlign": {
+            "target": "config",
+            "writeKey": "tabAlign",
+            "values": [
+                "center",
+                "left",
+                "right"
+            ],
+            "readBy": "TAB_ALIGNS (VOCAB in schema/src/elements/tab/meta.ts)"
         }
     },
     "spline-scene": {
+        "eventsTarget": {
+            "target": "config",
+            "writeKey": "eventsTarget",
+            "values": [
+                "global",
+                "local"
+            ],
+            "readBy": "SCENE_EVENTS_TARGETS (VOCAB in schema/src/elements/spline-scene/meta.ts)"
+        },
+        "mobileMode": {
+            "target": "config",
+            "writeKey": "mobileMode",
+            "values": [
+                "poster",
+                "scene"
+            ],
+            "readBy": "SCENE_MOBILE_MODES (VOCAB in schema/src/elements/spline-scene/meta.ts)"
+        },
+        "effectColors": {
+            "target": "config",
+            "writeKey": "effectColors",
+            "values": [
+                "custom",
+                "theme"
+            ],
+            "readBy": "SCENE_COLOR_MODES (VOCAB in schema/src/elements/spline-scene/meta.ts)"
+        },
         "source": {
             "target": "specials",
             "writeKey": "source",
@@ -36980,6 +37054,15 @@ export const ELEMENT_VALUES = {
             ],
             "readBy": "SCENE_SOURCES (schema/src/elements/spline-scene/meta.ts)"
         },
+        "sceneViewer": {
+            "target": "specials",
+            "writeKey": "sceneViewer",
+            "values": [
+                "off",
+                "on"
+            ],
+            "readBy": "SCENE_VIEWER_MODES (schema/src/elements/spline-scene/meta.ts)"
+        },
         "effect": {
             "target": "config",
             "writeKey": "effect",
@@ -37012,7 +37095,7 @@ export const ELEMENT_VALUES = {
                 "normal",
                 "slow"
             ],
-            "readBy": "SCENE_SPEEDS (schema/src/elements/spline-scene/meta.ts)"
+            "readBy": "SCENE_SPEEDS (VOCAB in schema/src/elements/spline-scene/meta.ts)"
         },
         "intensity": {
             "target": "config",
@@ -37022,16 +37105,41 @@ export const ELEMENT_VALUES = {
                 "soft",
                 "strong"
             ],
-            "readBy": "SCENE_INTENSITIES (schema/src/elements/spline-scene/meta.ts)"
-        },
-        "effectColors": {
+            "readBy": "SCENE_INTENSITIES (VOCAB in schema/src/elements/spline-scene/meta.ts)"
+        }
+    },
+    "text-marquee": {
+        "marqueeDirection": {
             "target": "config",
-            "writeKey": "effectColors",
+            "writeKey": "marqueeDirection",
             "values": [
-                "custom",
-                "theme"
+                "left",
+                "right"
+            ],
+            "readBy": "MARQUEE_DIRECTIONS (VOCAB in schema/src/elements/text-marquee/meta.ts)"
+        }
+    },
+    "google-map": {
+        "mapType": {
+            "target": "specials",
+            "writeKey": "mapType",
+            "values": [
+                "code",
+                "location"
             ],
-            "readBy": "COLOR_MODES (editor/src/components/inspector/ScenePaletteRows.vue)"
+            "readBy": "MAP_TYPES (VOCAB in schema/src/elements/google-map/meta.ts)"
+        }
+    },
+    "form-file": {
+        "fileFormat": {
+            "target": "specials",
+            "writeKey": "fileFormat",
+            "values": [
+                "image",
+                "pdf",
+                "video"
+            ],
+            "readBy": "FILE_FORMATS (VOCAB in schema/src/elements/form-file/meta.ts)"
         }
     },
     "form-select": {
@@ -37060,6 +37168,17 @@ export const ELEMENT_VALUES = {
             "readBy": "OPTION_SOURCES (schema/src/elements/formOptionSource.ts)"
         }
     },
+    "form-payment": {
+        "logoShape": {
+            "target": "specials",
+            "writeKey": "logoShape",
+            "values": [
+                "auto",
+                "square"
+            ],
+            "readBy": "PAY_LOGO_SHAPES (VOCAB in schema/src/elements/form-payment/meta.ts)"
+        }
+    },
     "form-checkbox": {
         "optionSource": {
             "target": "config",
@@ -37116,6 +37235,94 @@ export const ELEMENT_VALUES = {
             "readBy": "DATE_PICKERS (schema/src/elements/form-calendar/meta.ts)"
         }
     },
+    "locale-switcher": {
+        "variant": {
+            "target": "specials",
+            "writeKey": "variant",
+            "values": [
+                "dropdown",
+                "inline",
+                "panel",
+                "select"
+            ],
+            "readBy": "LOCALE_SWITCH_VARIANTS (VOCAB in schema/src/elements/locale-switcher/meta.ts)"
+        },
+        "locale_switch_label": {
+            "target": "specials",
+            "writeKey": "labelMode",
+            "values": [
+                "code",
+                "name",
+                "both",
+                "currency"
+            ],
+            "readBy": "locale_switch_label (editor picker)"
+        }
+    },
+    "theme-switcher": {
+        "variant": {
+            "target": "specials",
+            "writeKey": "variant",
+            "values": [
+                "icon",
+                "segmented",
+                "switch"
+            ],
+            "readBy": "THEME_SWITCH_VARIANTS (VOCAB in schema/src/elements/theme-switcher/meta.ts)"
+        }
+    },
+    "image-marquee": {
+        "marqueeDirection": {
+            "target": "config",
+            "writeKey": "marqueeDirection",
+            "values": [
+                "left",
+                "right"
+            ],
+            "readBy": "MARQUEE_DIRECTIONS (VOCAB in schema/src/elements/image-marquee/meta.ts)"
+        }
+    },
+    "menu": {
+        "expandType": {
+            "target": "config",
+            "writeKey": "expandType",
+            "values": [
+                "click",
+                "hover"
+            ],
+            "readBy": "EXPAND_TYPES (VOCAB in schema/src/elements/menu/meta.ts)"
+        },
+        "submenuStyle": {
+            "target": "config",
+            "writeKey": "submenuStyle",
+            "values": [
+                "cascade",
+                "collapse",
+                "dropdown"
+            ],
+            "readBy": "SUBMENU_STYLES (VOCAB in schema/src/elements/menu/meta.ts)"
+        }
+    },
+    "chat-widget": {
+        "side": {
+            "target": "config",
+            "writeKey": "side",
+            "values": [
+                "left",
+                "right"
+            ],
+            "readBy": "CHAT_HSIDES (VOCAB in schema/src/elements/chat-widget/meta.ts)"
+        },
+        "vside": {
+            "target": "config",
+            "writeKey": "vside",
+            "values": [
+                "bottom",
+                "top"
+            ],
+            "readBy": "CHAT_VSIDES (VOCAB in schema/src/elements/chat-widget/meta.ts)"
+        }
+    },
     "*": {
         "backgroundSceneSource": {
             "target": "config",
@@ -37180,7 +37387,7 @@ export const ELEMENT_VALUES = {
                 "custom",
                 "theme"
             ],
-            "readBy": "COLOR_MODES (editor/src/components/inspector/ScenePaletteRows.vue)"
+            "readBy": "SCENE_COLOR_MODES (schema/src/elements/spline-scene/meta.ts)"
         }
     },
     "filter-checkbox": {
@@ -37487,19 +37694,6 @@ export const ELEMENT_VALUES = {
             "readBy": "cart_total_part (editor picker)"
         }
     },
-    "locale-switcher": {
-        "locale_switch_label": {
-            "target": "specials",
-            "writeKey": "labelMode",
-            "values": [
-                "code",
-                "name",
-                "both",
-                "currency"
-            ],
-            "readBy": "locale_switch_label (editor picker)"
-        }
-    },
     "member-field": {
         "member_field_source": {
             "target": "specials",
@@ -37635,6 +37829,32 @@ export const ELEMENT_VALUES = {
             ],
             "readBy": "qr_source (editor picker)"
         }
+    },
+    "cart-drawer": {
+        "direct": {
+            "target": "config",
+            "writeKey": "direct",
+            "values": [
+                "bottom",
+                "left",
+                "right",
+                "top"
+            ],
+            "readBy": "DRAWER_EDGES (VOCAB in schema/src/elements/cart-drawer/meta.ts)"
+        }
+    },
+    "hamburger-menu": {
+        "direct": {
+            "target": "config",
+            "writeKey": "direct",
+            "values": [
+                "bottom",
+                "left",
+                "right",
+                "top"
+            ],
+            "readBy": "DRAWER_EDGES (VOCAB in schema/src/elements/hamburger-menu/meta.ts)"
+        }
     }
 };
 /**

package/dist/catalog/search.js

@@ -76,6 +76,199 @@ export function searchOperations(query, opts = {}) {
  * Saying "no body" for the second group would be the silent failure — the model
  * would send an empty PUT and wipe a page. So the two get different words.
  */
+/**
+ * ONE DOC BLOCK OVER SEVERAL `@Router` LINES, AND THE SUMMARY IS THE HALF
+ * NOTHING CORRECTED.
+ *
+ * This file already records the defect for BODIES — swag attaches one comment
+ * block's `@Param body` to every route beneath it, so a listing GET claimed a
+ * body it does not take — and the fix was to read the decode site instead. The
+ * SUMMARY is copied by the same mechanism and has no such correction: 302 of
+ * 524 operations share a summary with another operation.
+ *
+ * MOST OF THAT IS HARMLESS AND MUST NOT BE FLAGGED. "List, create, update or
+ * delete a course's lessons" on all four CRUD routes is an UMBRELLA — it names
+ * the whole group and is true of each member, and 105 of the 119 shared
+ * summaries are that shape. Flagging them would bury the ones that matter.
+ *
+ * THE DISCRIMINATOR IS THE TRAILING LITERAL SEGMENT, which is the same signal
+ * `scripts/shapes.ts` already trusts to pick a handler out of a dispatcher that
+ * routes by path ("the route's own trailing literal segment picks the callee").
+ * Operations sharing a summary while differing only by METHOD or by a trailing
+ * `{param}` are one resource; ones whose literal tails DIFFER are separate
+ * ACTIONS, and one sentence can describe at most one of them. That leaves 14
+ * groups and 41 operations.
+ *
+ * WHY THIS IS WORTH A FIELD. The costliest is money: this platform documents
+ * `/refund` as RECORDING a refund made elsewhere and `/refund-via-gateway` as
+ * ASKING the gateway to send it, and the catalog gives BOTH — plus `POST
+ * /payment-transactions`, which opens a pay link — the single summary "ASK the
+ * gateway to send the money back". An agent asked to refund a customer reaches
+ * for the obvious name, reads a sentence promising the money moves, and records
+ * a refund that never pays anybody. `POST .../versions` (snapshot) and
+ * `.../restore` share one summary while running in OPPOSITE directions, and
+ * `/invitations/{id}/accept` and `/decline` are both described as "Withdraw an
+ * invitation".
+ *
+ * IT REPORTS THE COVERAGE AND NEVER GUESSES THE MISSING SENTENCE. The per-route
+ * text does exist — in each package's route-map comment — but those maps write
+ * paths relatively, abbreviate methods (`PATCH/DEL`), carry query strings and
+ * often no description at all, so recovering a summary from them would invent
+ * exactly the kind of confident wrong sentence this exists to remove. Naming
+ * the routes the sentence covers is knowable, is enough for the agent to read
+ * the path instead, and cannot be wrong.
+ *
+ * Derived from the catalog rather than generated into it: it is a fact ABOUT
+ * the document, not one read off the platform, so generating it would ship a
+ * table restating data the same file already carries.
+ */
+const summaryCoverage = (() => {
+    let byId = null;
+    /** The last segment that is not a `{param}` — an action tail, or a resource. */
+    const tail = (path) => {
+        const literal = path.split('/').filter((seg) => seg && !seg.startsWith('{'));
+        return literal[literal.length - 1] ?? '';
+    };
+    const build = () => {
+        const groups = new Map();
+        for (const op of API_OPERATIONS) {
+            if (!op.summary)
+                continue;
+            const g = groups.get(op.summary);
+            if (g)
+                g.push(op);
+            else
+                groups.set(op.summary, [op]);
+        }
+        const out = new Map();
+        for (const members of groups.values()) {
+            if (members.length < 2)
+                continue;
+            if (new Set(members.map((m) => tail(m.path))).size < 2)
+                continue;
+            for (const op of members) {
+                out.set(op.id, members.filter((m) => m.id !== op.id).map((m) => `${m.method} ${m.path}`));
+            }
+        }
+        return out;
+    };
+    return (id) => (byId ??= build()).get(id);
+})();
+/** Whether this operation's summary is one the platform wrote for a group. */
+export function summaryIsShared(id) {
+    return summaryCoverage(id) !== undefined;
+}
+/**
+ * THE PARAMS, ONCE EACH.
+ *
+ * The stacked block copies `@Param` lines as well as prose, so an operation in
+ * a group of four carries `siteId` four times: 29 operations list a parameter
+ * more than once, and `POST /payment-transactions` reports `siteId` three
+ * times. It is noise in the one field an agent reads to build the call, and it
+ * costs tokens on every search line.
+ *
+ * Deduplicated by NAME AND LOCATION, which is what identifies a parameter on
+ * the wire — two entries agreeing on both are one parameter however many blocks
+ * declared it. The first is kept, so a description is never invented or merged.
+ * No operation claims a path param its own path lacks (measured), so the
+ * deduplication only ever removes a repeat.
+ *
+ * AND THE PATH IS THE AUTHORITY ON WHAT THE CALL NEEDS, which is the other
+ * direction and was costing a round trip. THIRTY operations declare a `{param}`
+ * in their path that the document lists under no `@Param` at all —
+ * `POST /api/sites/{siteId}/pages` lists NONE of its own, and
+ * `PUT /api/sites/{siteId}/courses/{id}/questions/{questionId}` lists every one
+ * but `questionId`. `callOperation` already ignores this list and walks the
+ * PATH, so the call is not broken; what breaks is the agent, which reads
+ * `params`, sends what it says, and is told it is missing an argument the sheet
+ * never mentioned. Synthesised here so the sheet says what the call demands,
+ * and marked so nobody mistakes it for something the platform described.
+ */
+function visibleParams(op) {
+    const seen = new Set();
+    const out = op.params.filter((p) => {
+        if (p.in === 'body')
+            return false;
+        const id = `${p.in}:${p.name}`;
+        if (seen.has(id))
+            return false;
+        seen.add(id);
+        return true;
+    });
+    for (const m of op.path.matchAll(/\{([^}]+)\}/g)) {
+        if (seen.has(`path:${m[1]}`))
+            continue;
+        seen.add(`path:${m[1]}`);
+        out.push({
+            name: m[1],
+            in: 'path',
+            required: true,
+            type: 'string',
+            description: 'In the path, and undocumented — recovered from the route itself.',
+        });
+    }
+    return out;
+}
+/**
+ * A READ THAT CLAIMS A BODY IS CLAIMING ITS NEIGHBOUR'S.
+ *
+ * The same stacking that copies a summary copies every `@Param` in the block,
+ * so 90 GET and DELETE operations declare a request body. `describeOperation`
+ * believed them and inlined the DEFINITION: measured, ~83 KB of body schema
+ * across those 90 call sheets — about 927 bytes each — describing a body the
+ * route cannot take. `GET /api/sites/{siteId}/customers`, a listing, ships the
+ * whole customer object and reports `body: "described"`.
+ *
+ * THE DECODE SITES CANNOT ANSWER THIS ONE, and reading their silence as a no
+ * would be the mistake this repo already records in another form ("the absence
+ * of a string is evidence about the string, not about the behaviour").
+ * `scripts/shapes.ts` sets `WRITE_METHODS = POST | PUT | PATCH` and never looks
+ * at a read, so "0 of 90 confirmed" is structural, not a finding.
+ *
+ * SO THE TEST IS THE MECHANISM ITSELF, which is visible in the document. A
+ * stacked block gives every route the SAME `@Param`, byte for byte — name, type
+ * and description. MEASURED: all 90 carry a body param identical to some write
+ * operation's, and for 86 that donor is on the same path or the same resource,
+ * which is a doc block covering several methods. That is the copy caught in the
+ * act, not an assumption about what a GET may carry.
+ *
+ * It answers only for reads. A WRITE's body claim stays believed: this file
+ * already records that most writes are UNDER-annotated, and `PUT
+ * /pages/{id}/source` carries a whole page document while declaring nothing —
+ * so the risk there runs the other way and a shared `@Param` may be the only
+ * description of a real body.
+ */
+const copiedBodyDonor = (() => {
+    let byId = null;
+    const sig = (p) => JSON.stringify([p.name, p.type, p.description]);
+    const build = () => {
+        const donors = new Map();
+        for (const op of API_OPERATIONS) {
+            if (op.method !== 'POST' && op.method !== 'PUT' && op.method !== 'PATCH')
+                continue;
+            for (const p of op.params)
+                if (p.in === 'body' && !donors.has(sig(p)))
+                    donors.set(sig(p), op);
+        }
+        const out = new Map();
+        for (const op of API_OPERATIONS) {
+            if (op.method !== 'GET' && op.method !== 'DELETE')
+                continue;
+            const bodies = op.params.filter((p) => p.in === 'body');
+            if (!bodies.length)
+                continue;
+            // EVERY one must be accounted for. A read carrying one copied param and
+            // one of its own would be a shape nothing here has seen, and the honest
+            // answer to that is to say nothing and leave the document's claim alone.
+            const found = bodies.map((p) => donors.get(sig(p)));
+            if (found.some((d) => d === undefined))
+                continue;
+            out.set(op.id, `${found[0].method} ${found[0].path}`);
+        }
+        return out;
+    };
+    return (id) => (byId ??= build()).get(id);
+})();
 export function describeOperation(op) {
     const out = {
         id: op.id,
@@ -84,8 +277,14 @@ export function describeOperation(op) {
         summary: op.summary,
         tags: op.tags,
         credential: op.credential,
-        params: op.params.filter((p) => p.in !== 'body'),
+        params: visibleParams(op),
     };
+    // SAY WHO ELSE THE SENTENCE ABOVE IS ABOUT. Placed directly under `summary`
+    // because that is the field it qualifies: an agent that has read the sentence
+    // and moved on has already taken the wrong operation.
+    const covers = summaryCoverage(op.id);
+    if (covers)
+        out.summary_covers = covers;
     const hasBody = op.params.some((p) => p.in === 'body');
     const isWrite = op.method === 'POST' || op.method === 'PUT' || op.method === 'PATCH';
     // THE HANDLER OUTRANKS THE DOCUMENT. `swagger.json` describes 46 of 212 write
@@ -172,6 +371,16 @@ export function describeOperation(op) {
         out.body_shape = shape;
         return out;
     }
+    // Said BEFORE the body branches, because the whole point is not to inline a
+    // definition for a body this route does not take.
+    const copiedFrom = copiedBodyDonor(op.id);
+    if (copiedFrom) {
+        out.body_note =
+            `The document declares a request body here, and it is a VERBATIM copy of ${copiedFrom}'s ` +
+                '— one doc comment over several @Router lines gives every route in the block the same ' +
+                '@Param. Send no body; the schema is that other route\'s.';
+        return out;
+    }
     if (hasBody && op.bodyDescribed && op.bodyRef) {
         out.body_schema = API_DEFINITIONS[op.bodyRef];
     }
@@ -209,9 +418,16 @@ export function summarizeOperation(op) {
         path: op.path,
         summary: op.summary,
         credential: op.credential,
-        params: op.params.filter((p) => p.in !== 'body').map((p) => (p.required ? p.name : `?${p.name}`)),
+        params: visibleParams(op).map((p) => (p.required ? p.name : `?${p.name}`)),
     };
-    if (hasBody)
+    // ONE BOOLEAN, because this line is where the CHOICE is made and a search hit
+    // must stay a line. It says only "this sentence was written for a group of
+    // routes, so read the path"; the call sheet names the group.
+    if (summaryIsShared(op.id))
+        out.summary_shared = true;
+    // A copied body is not this route's, so the line says nothing rather than
+    // `described` — see `copiedBodyDonor`.
+    if (hasBody && !copiedBodyDonor(op.id))
         out.body = op.bodyDescribed && op.bodyRef ? 'described' : 'undescribed';
     else if (isWrite)
         out.body = 'none_declared';

package/dist/catalog/shapes.generated.js

@@ -4,7 +4,7 @@ export const SHAPE_SOURCE = {
     "fromHandlers": 175,
     "fromSwaggerOnly": 0,
     "withReadOnly": 26,
-    "structsRead": 1660
+    "structsRead": 1661
 };
 export const REQUEST_SHAPES = {
     "post:/api/sites/{siteId}/api-keys": {

package/dist/catalog/translations.generated.js

@@ -3,7 +3,7 @@
 export const TRANSLATION_SOURCE = {
     "elements": 58,
     "pairs": 142,
-    "neverKeys": 163,
+    "neverKeys": 164,
     "entityTypes": 12
 };
 /** Every entity type a translation record can name, including "node". */
@@ -417,6 +417,7 @@ export const NEVER_TRANSLATED = [
     "sceneControls",
     "sceneGallery",
     "sceneUrl",
+    "sceneViewer",
     "searchBehavior",
     "searchClearSwap",
     "searchDebounceMs",

package/dist/domains/site/vocabulary.js

@@ -128,10 +128,15 @@ export function vocabularyForWrite(type, namespace, key) {
  *     `mediaImageRatio: "4 / 5"` is CORRECT and reporting it would send a caller
  *     to "fix" a working page — the same cost this repo already records for the
  *     `category` alias. Nothing is said at all.
- *   - A FALLBACK IS ONLY CLAIMED WHERE THE SOURCE SAYS ONE. The editor's picker
- *     proves what an author may choose and is silent on what the renderer does
- *     with anything else. Naming a fallback there would be the invention this
- *     table exists to remove, so the note says what it knows and stops.
+ *   - A FALLBACK IS ONLY CLAIMED WHERE A SOURCE SAYS ONE, AND IT IS CREDITED TO
+ *     THAT SOURCE. The editor's picker proves what an author may choose and is
+ *     silent on what the renderer does with anything else. Naming a fallback
+ *     there would be the invention this table exists to remove, so the note says
+ *     what it knows and stops. Where a schema declaration has SUPERSEDED a Go
+ *     reading the two halves come from different places — the list says which
+ *     words mean something, the renderer's `default:` arm says what an unknown
+ *     one renders as — so the sentence names `fallbackReadBy`, not the
+ *     declaration, which normalises nothing.
  */
 export function unknownWriteNote(type, namespace, key, value) {
     const vocab = vocabularyForWrite(type, namespace, key);
@@ -144,7 +149,7 @@ export function unknownWriteNote(type, namespace, key, value) {
     const list = vocab.values.map((v) => (v === '' ? '"" (unset)' : v)).join(', ');
     return (`${namespace}.${key} = ${JSON.stringify(value)} is not a value ${type}'s renderer knows. ` +
         (vocab.fallback !== undefined
-            ? `${vocab.readBy} normalises anything unrecognised to ${vocab.fallback === '' ? '"" (unset)' : `"${vocab.fallback}"`}, so this stores, saves and publishes with no error and renders as that. `
+            ? `${vocab.fallbackReadBy ?? vocab.readBy} normalises anything unrecognised to ${vocab.fallback === '' ? '"" (unset)' : `"${vocab.fallback}"`}, so this stores, saves and publishes with no error and renders as that. `
             : `${vocab.readBy} is the source, and it is silent on what the renderer does with a word ` +
                 'outside the list — every comparable key in this catalog normalises silently rather ' +
                 'than erroring. ') +

package/dist/tools/api.js

@@ -303,6 +303,20 @@ export async function callOperation(ctx, args) {
     const projection = args.pick ?? LIST_PROJECTIONS[op.id];
     return shapeResponse(raw, { pick: projection, max_items: args.max_items });
 }
+/**
+ * WHY A SUMMARY CAN BE ABOUT A DIFFERENT ROUTE.
+ *
+ * The platform stacks ONE doc comment over several `@Router` lines and swag
+ * copies it to each, so the summary — and the description, which it also merges
+ * across blocks — belongs to the group rather than to the route. This repo
+ * already corrects the same defect for BODIES by reading the decode site; there
+ * is no such correction for prose, and no per-route sentence exists to recover.
+ */
+const SHARED_SUMMARY_NOTICE = 'summary_covers means the platform wrote that one sentence for several routes at once (one ' +
+    'doc comment over several @Router lines), so it may describe one of the listed routes rather ' +
+    'than this one — trust the PATH and the body shape, not the sentence. The sharpest case is ' +
+    'money: /payment-transactions/{id}/refund only RECORDS a refund made elsewhere, while ' +
+    '/refund-via-gateway is the one that asks the gateway to actually send it.';
 export function registerApiTools(server, ctx) {
     server.registerTool('sb_api_find', {
         description: 'Search platform API operations by intent (query: one line per match), or read one ' +
@@ -327,7 +341,13 @@ export function registerApiTools(server, ctx) {
             const op = findOperation(id);
             if (!op)
                 throw new Error(`sbuilder: unknown operation "${id}" — search with query first`);
-            return text(describeOperation(op));
+            const sheet = describeOperation(op);
+            // The WHY is a directive, so it is said once per process; the routes it
+            // covers are DATA and ride on every sheet that has them.
+            const why = sheet.summary_covers
+                ? ctx.notices.once('shared_summary', SHARED_SUMMARY_NOTICE)
+                : undefined;
+            return text(why ? { ...sheet, directive: why } : sheet);
         }
         if (!query) {
             throw new Error('sbuilder: sb_api_find needs a query (search) or an id (call sheet)');

package/dist/tools/page.js

@@ -311,6 +311,29 @@ async function siteChrome(ctx, siteId) {
         return {};
     }
 }
+/**
+ * The site's own home page, or null when it genuinely has none.
+ *
+ * THROWS RATHER THAN GUESSES. Answering "none" for a listing that could not be
+ * read is the one wrong answer available here: it is indistinguishable from an
+ * empty site, and the caller acts on it by creating a home page the site
+ * already had. `siteChrome` above may swallow its read because a page created
+ * without chrome is a page a person can fix; this one may not, because the page
+ * it creates cannot be un-created and takes the star off whichever page held it.
+ */
+async function existingHomepage(ctx, siteId) {
+    const listed = (await request({
+        base: ctx.base,
+        method: 'GET',
+        path: `/api/sites/${encodeURIComponent(siteId)}/pages`,
+        token: siteToken(ctx),
+        fetchImpl: ctx.fetchImpl,
+    }));
+    const home = (listed.pages ?? []).find((p) => p.isHomepage === true);
+    if (!home || typeof home.id !== 'string' || !home.id)
+        return null;
+    return { id: home.id, name: typeof home.name === 'string' ? home.name : '' };
+}
 export function registerPageTools(server, ctx) {
     const session = new PageSession(ctx);
     server.registerTool('sb_page_open', {
@@ -1012,7 +1035,85 @@ export function registerPageTools(server, ctx) {
         // fine, while `siteChrome` asks whether the SITE has globals and it does.
         // Measured: three pages built with these tools, every one of them bare,
         // beside a store page carrying its header as ROOT's first child.
-        const wear = chrome !== false ? await siteChrome(ctx, site_id) : {};
+        // A SITE HAS ONE HOME PAGE, AND BY THE TIME AN AGENT ASKS FOR ONE IT
+        // USUALLY EXISTS ALREADY.
+        //
+        // `isHomepage: true` does not mean "make this the home page" to the
+        // platform. It means MOVE THE STAR: CreatePage demotes whoever holds it
+        // and promotes this one. An agent building a store reads the flag the
+        // first way and asks for it on a site the editor already gave a home page
+        // to, so the site ends up with two — the new one on "/", the old one
+        // demoted and holding nothing. Measured on a real store: pg_439cb121
+        // "Home" and pg_237719d4 "Trang chủ", both slug "", both path "/", the
+        // first reachable at no address at all and still listed as a page.
+        //
+        // So the flag is honoured as what the caller meant — the site's home page
+        // — which is the one it already has. Adopted, renamed when the caller
+        // named it something else, never duplicated. The same rule sb_import_site
+        // already follows when its entry page lands on a site with a home page.
+        //
+        // REPLACING the home page with a DIFFERENT page stays possible and stays
+        // explicit: create it without the flag, build it, then PATCH isHomepage
+        // through sb_api_call. That is a decision, and it should read like one.
+        const adopt = is_homepage === true ? await existingHomepage(ctx, site_id) : null;
+        const rename = adopt && name.trim() !== '' && name !== adopt.name ? name : '';
+        // Read AFTER the adopt decision and skipped when it holds: siteChrome
+        // reads the header and footer off the home page, so asking it which
+        // chrome to dress the home page in is two requests to answer "its own".
+        const wear = chrome !== false && !adopt ? await siteChrome(ctx, site_id) : {};
+        if (adopt && dry_run !== false) {
+            return text({
+                dry_run: true,
+                into: 'the existing home page',
+                page: adopt,
+                ...(rename ? { would_rename: { from: adopt.name, to: rename } } : {}),
+                note: 'Nothing would be created. This site already has a home page and a site has ' +
+                    'exactly one, so a create carrying isHomepage would have taken the star off ' +
+                    `${JSON.stringify(adopt.name)} and left it with no address. Open ${adopt.id} ` +
+                    'with sb_page_open and build it.',
+            });
+        }
+        if (adopt) {
+            // THE RENAME IS THE ONLY WRITE. Not the seed — this page may already be
+            // the site's front door, and overwriting a document nobody asked to
+            // replace is the one thing worse than the duplicate this branch exists
+            // to prevent. Not the chrome either: siteChrome reads the header and
+            // footer OFF the home page, so this page is where they came from.
+            let renamed_to;
+            let rename_failed;
+            if (rename) {
+                try {
+                    await request({
+                        base: ctx.base,
+                        method: 'PATCH',
+                        path: `${path}/${encodeURIComponent(adopt.id)}`,
+                        token: siteToken(ctx),
+                        body: { name: rename },
+                        fetchImpl: ctx.fetchImpl,
+                    });
+                    renamed_to = rename;
+                }
+                catch (e) {
+                    // The page is still the right one to build on, so a failed rename
+                    // is reported, never raised — the caller asked for a home page and
+                    // this is it, under its old name.
+                    rename_failed = e.message.replace(/^sbuilder:\s*/, '').slice(0, 160);
+                }
+            }
+            return text({
+                into: 'the existing home page',
+                page: { id: adopt.id, name: renamed_to ?? adopt.name },
+                ...(renamed_to ? { renamed: { from: adopt.name, to: renamed_to } } : {}),
+                ...(rename_failed ? { rename_failed } : {}),
+                ...(slug ? { slug_ignored: 'A home page is served at "/" and carries no slug.' } : {}),
+                ...(type && type !== 'page' ? { type_ignored: `Kept as it is; adopting does not retype a page to "${type}".` } : {}),
+                note: 'Nothing was created. This site already had a home page and a site has exactly ' +
+                    'one, so creating another would have taken the star off this page and left it ' +
+                    `with no address. Open ${adopt.id} with sb_page_open and build it. To hand the ` +
+                    'home page over to a DIFFERENT page instead, create that page WITHOUT ' +
+                    'is_homepage and then PATCH isHomepage on it through sb_api_call.',
+            });
+        }
         if (dry_run !== false) {
             return text({
                 dry_run: true,

package/package.json

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