sbuilder-mcp 0.48.1 → 0.50.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.50.0] - 2026-09-15
+
+### Changed
+- `sb_catalog_search` raises its `limit` ceiling from 30 to 60 so a category can be read whole; the `basic` category alone holds 39 element types, and a 30-cap silently dropped the nine an agent had never used, the same failure browsing exists to fix.
+- `sb_catalog_search`'s browse note now tells the caller to pass a category name with `limit` 60 to read that whole group's descriptions at once, on top of passing a type for its fields.
+
+## [0.49.0] - 2026-09-15
+
+### Added
+- `sb_catalog_search` now returns every element type, grouped by category, when `query` is omitted, so an agent can browse the catalogue instead of only searching for a name it already knows.
+- `sb_review` reports a `handbuilt_menu` finding when a header contains three or more sibling buttons and nothing else, since a row of buttons cannot supply the mobile drawer, sub-level dropdown, or active state that the platform's own `menu` element brings.
+- Opening a page now joins the live-edit room on its own, through `sb_page_open`, `sb_page_create`, and `sb_template_use` alike, instead of requiring a separate `sb_live_join` call that an agent has to remember to make; a write retries the join if an earlier attempt failed, and `sb_page_open` reports when it newly joined the room or could not.
+- `sb_connect` now mentions the live-edit room in its connect note, in the one place an agent is guaranteed to read on the way in.
+
+### Fixed
+- A page whose read came back empty because the fetch failed open no longer risks silently emptying the page on save; `sb_page_open` now reports a `seeded_empty` warning on that page, and `PageSession.save` re-checks the server before writing and refuses the save if the server actually holds content, asking the caller to re-open and reapply instead.
+
 ## [0.48.1] - 2026-09-14
 
 ### Fixed

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.50.0] - 2026-09-15
+
+### Changed
+- `sb_catalog_search` nâng trần `limit` từ 30 lên 60 để có thể đọc trọn một category; riêng category `basic` đã có 39 loại phần tử, và mức trần 30 âm thầm bỏ sót chín phần tử mà agent chưa từng dùng đến — đúng lỗi mà tính năng duyệt catalog vốn sinh ra để khắc phục.
+- Ghi chú duyệt catalog của `sb_catalog_search` giờ hướng dẫn người gọi truyền tên một category cùng `limit` 60 để đọc toàn bộ mô tả của nhóm đó một lần, bên cạnh việc truyền một loại phần tử để xem các trường lựa chọn của nó.
+
+## [0.49.0] - 2026-09-15
+
+### Added
+- `sb_catalog_search` giờ trả về mọi loại phần tử, nhóm theo category, khi bỏ trống `query`, nhờ đó agent có thể duyệt qua toàn bộ catalog thay vì chỉ tìm kiếm theo tên đã biết trước.
+- `sb_review` giờ báo lỗi `handbuilt_menu` khi một header chứa từ ba nút button anh em trở lên và không có gì khác, vì một hàng button không thể thay thế drawer cho điện thoại, dropdown cho cấp con, hay trạng thái active cho trang khách đang xem — những thứ mà phần tử `menu` của nền tảng mang lại.
+- Việc mở một trang giờ tự động tham gia phòng live-edit, qua cả `sb_page_open`, `sb_page_create` lẫn `sb_template_use`, thay vì phải gọi riêng `sb_live_join` mà agent phải tự nhớ; một lần ghi sẽ thử tham gia lại nếu lần trước thất bại, và `sb_page_open` báo cáo khi nó vừa tham gia phòng thành công hay không thể.
+- `sb_connect` giờ nhắc đến phòng live-edit trong ghi chú kết nối, ngay tại nơi chắc chắn agent sẽ đọc khi mới vào.
+
+### Fixed
+- Một lần đọc trang trả về rỗng vì việc fetch thất bại theo kiểu "mở" giờ không còn nguy cơ âm thầm xoá sạch trang khi lưu; `sb_page_open` giờ báo cảnh báo `seeded_empty` trên trang đó, và `PageSession.save` kiểm tra lại với server trước khi ghi, từ chối lưu nếu server thực sự đang giữ nội dung, và yêu cầu người gọi mở lại trang rồi áp dụng lại thay đổi.
+
 ## [0.48.1] - 2026-09-14
 
 ### Fixed

package/dist/catalog/element-search.js

@@ -3,6 +3,51 @@ import { animationValues, animationVocabulary, elementVocabularies, sharedVocabu
 import { neverTranslatedOn, translatableSpecials } from '../domains/site/translate.js';
 /** Eight to choose from; the hints for the chosen one come with sb_traits_for. */
 export const DEFAULT_CATALOG_LIMIT = 8;
+/**
+ * EVERY element there is, grouped the way the palette files them.
+ *
+ * `catalogMatches` below is a SEARCH, and a search only returns what the caller
+ * already thought to ask for. Measured on a store built with these tools: the
+ * home page used 17 element types out of the hundred-odd here, and the ones it
+ * reached for were the five primitives any agent already knows — flex-block,
+ * text, heading, button, image. Four category cards were hand-assembled out of
+ * them; so were four feature blocks and a stats row. The header's navigation
+ * was SIX BUTTONS in a flex-block, on a platform carrying menu, menu-item,
+ * menu-dropdown, menu-panel, menu-drawer and hamburger-menu — so that site has
+ * no mobile menu at all, and nothing said so.
+ *
+ * None of that is the agent being careless. It is a catalogue you can only
+ * query by name refusing to tell anyone what is in it: rating-stars, carousel,
+ * tab, google-map, image-comparison, text-marquee, video, quickview,
+ * currency-switcher and popup cannot be searched for by someone who does not
+ * know they exist.
+ *
+ * TYPE AND LABEL ONLY, no descriptions. This is the list you read to find out
+ * what is POSSIBLE; `catalogMatches(type)` gives the four fields to choose by
+ * and `sb_traits_for` the hints, so repeating a description per element here
+ * would pay for the whole catalogue to answer a question about one element.
+ */
+export function catalogBrowse() {
+    const out = {};
+    for (const el of Object.values(ELEMENTS)) {
+        (out[el.category] ??= []).push(`${el.type} — ${el.label}`);
+    }
+    for (const k of Object.keys(out))
+        out[k].sort();
+    return out;
+}
+/**
+ * The biggest category, which is what `limit` has to clear for a caller to read
+ * one group WHOLE.
+ *
+ * A group query that silently returns its first 30 of 39 is the worst answer
+ * available here: it looks like the whole group, and the nine it dropped are
+ * exactly the elements nobody knew to look for. `catalog-browse.test.ts` fails
+ * when a category outgrows the cap, which is the only way anyone would notice.
+ */
+export function largestCategorySize() {
+    return Math.max(...Object.values(catalogBrowse()).map((g) => g.length));
+}
 /**
  * Four fields to CHOOSE by.
  *

package/dist/domains/site/document.js

@@ -57,7 +57,9 @@ export class PageDoc {
         // The genuinely broken case is still refused below: a document that HAS
         // nodes but whose root_node_id names none of them is damage, not emptiness,
         // and inventing a root there would strand every existing node as an orphan.
+        let seeded = false;
         if (!d.root_node_id && Object.keys(d.nodes).length === 0) {
+            seeded = true;
             d.root_node_id = 'ROOT';
             d.nodes.ROOT = {
                 id: 'ROOT',
@@ -105,6 +107,7 @@ export class PageDoc {
         }
         const out = new PageDoc(d);
         out.adoptedRootKey = adopted;
+        out.seededRoot = seeded;
         return out;
     }
     /**
@@ -114,6 +117,25 @@ export class PageDoc {
      * a fact no other surface reports, so the tool layer says it out loud.
      */
     adoptedRootKey;
+    /**
+     * This ROOT was INVENTED, not read — the source came back `{ root_node_id: "",
+     * nodes: {} }` and the empty-document branch above seeded one.
+     *
+     * For a page the caller has just created that is the whole point, and nothing
+     * downstream needs to care. For a page that HAS content it is a read that
+     * failed open: the session now holds a blank tree it believes is the page, and
+     * the first save writes that blank tree over whatever the server holds. The
+     * two are indistinguishable AT READ TIME — the bytes are identical — so the
+     * distinction cannot be made here and must survive to the one place that can
+     * check it cheaply, which is `PageSession.save`.
+     *
+     * MEASURED: a product template carrying 24 nodes plus a shared header and
+     * footer came back bare to one session and was stored bare. The published copy
+     * was untouched, so all 19 product pages kept rendering while the draft the
+     * editor opens was blank — one publish from that draft would have taken every
+     * one of them down.
+     */
+    seededRoot;
     get rev() {
         return this.revision;
     }

package/dist/domains/site/findings.js

@@ -42,6 +42,10 @@ export const FIX = {
         '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\'>" }.',
+    handbuilt_menu: 'Replace it with the real thing: sb_add a "menu" in place of the container "<id>", one ' +
+        '"menu-item" per link, and delete the buttons with sb_remove. Add a "menu-drawer" (with a ' +
+        '"hamburger-menu" trigger) for the phone, and "menu-dropdown" where a link has a sub-level. ' +
+        'sb_traits_for "menu" has the controls.',
     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.',

package/dist/domains/site/review.js

@@ -1,8 +1,25 @@
 import { childrenOf, childrenWithSatellites, isOverlay, pageChildren, appBlockRoot, SPEC_GLOBAL_REF, SPEC_APP_BLOCK_REF } from '../../core/tree.js';
 import { STUCK_STATE, stickyBlockedBy, stuckHostOf, isPinnedNode } from './sticky.js';
+import { bandOf } from './traps.js';
 import { HOVER_STATE, hoverHome } from './hover.js';
 import { ELEMENTS, BINDING_SOURCES, BOUND_SPECIALS, FIRST_CHILD_ONLY, SATELLITE_RULES, ELEMENT_SEEDS } from '../../catalog/elements.generated.js';
 import { fill } from './findings.js';
+/**
+ * A defect somebody looking at the page would see.
+ *
+ * Distinct from `validateForSave`, which asks "will the platform store this
+ * tree" — dangling ids, orphans, band order. This asks the question a person
+ * asks: does the page WORK. A document can be perfectly storable and render as a
+ * blank band saying "Enter your text here".
+ *
+ * Every finding names the fix, because a warning that only states a problem is
+ * one the reader has to re-derive.
+ */
+/**
+ * How many buttons in a row read as a navigation rather than as a pair of calls
+ * to action. Three: two side by side is the ordinary hero shape.
+ */
+const HANDBUILT_MENU_MIN = 3;
 /**
  * Shipped with every non-empty finding list.
  *
@@ -174,6 +191,61 @@ export function reviewDesign(doc) {
             go(k, inner, overlay || overlayIds.has(k));
     };
     go(d.root_node_id);
+    // WHICH BAND EACH NODE LIVES IN, taken from the top-level section it descends
+    // from. `bandOf` answers for a ROOT child; everything below one inherits it.
+    const band = new Map();
+    for (const sectionId of pageChildren(d)) {
+        const b = bandOf(d, sectionId);
+        const stack = [sectionId];
+        while (stack.length) {
+            const id = stack.pop();
+            if (band.has(id))
+                continue;
+            band.set(id, b);
+            for (const k of childrenWithSatellites(d, id))
+                stack.push(k);
+        }
+    }
+    // BUILT BY HAND OUT OF PRIMITIVES, WHERE THE PLATFORM HAS THE ELEMENT.
+    //
+    // Every other check here asks whether something is BROKEN. This one asks
+    // whether it was built with the wrong thing, which is the defect no amount of
+    // looking at the page reveals: it renders correctly on the screen the author
+    // is looking at, and fails on the one they are not.
+    //
+    // Measured on a store built with these tools: the header's navigation was six
+    // `button` nodes in a flex-block. It looks right on a desktop canvas. On a
+    // phone there is no drawer, because a drawer is something `menu` brings and a
+    // row of buttons does not — so the site shipped with no mobile navigation and
+    // nothing anywhere said so.
+    //
+    // A TABLE, because this will not be the only one. The next pattern is a row
+    // here, not a second branch somewhere else.
+    //
+    // DELIBERATELY NARROW. Three or more buttons, ALL the container's children,
+    // all leaves, and only in the HEADER band. A footer's link column is the same
+    // shape and is legitimately a list of links; a two-button pair is a call to
+    // action, not a menu. The check that fires on those is one an author learns to
+    // ignore, which costs more than the one it catches.
+    for (const [containerId, childIds] of [...Object.keys(d.nodes)].map((id) => [id, childrenOf(d, id)])) {
+        if (band.get(containerId) !== 'header')
+            continue;
+        if (childIds.length < HANDBUILT_MENU_MIN)
+            continue;
+        const allLeafButtons = childIds.every((k) => d.nodes[k]?.data.type === 'button' && childrenOf(d, k).length === 0);
+        if (!allLeafButtons)
+            continue;
+        out.push({
+            code: 'handbuilt_menu',
+            nodeId: containerId,
+            type: d.nodes[containerId]?.data.type ?? '',
+            problem: `${childIds.length} buttons in a row in the header is a navigation built by hand. It ` +
+                'renders correctly on a wide canvas and has no drawer on a phone, no dropdown for a ' +
+                'sub-level, and no active state on the page the visitor is already reading — all three ' +
+                'are things the menu element brings and a row of buttons cannot.',
+            fix: fill('handbuilt_menu', {}),
+        });
+    }
     for (const id of walkOrder) {
         if (id === d.root_node_id)
             continue;

package/dist/tools/live.js

@@ -208,7 +208,38 @@ export function liveTokenFor(ctx) {
     // carries the whole account.
     return () => (ctx.apiKey ? ctx.apiKey : ctx.session.token());
 }
+/**
+ * Open the room and hand it to the page session.
+ *
+ * EXTRACTED so joining is not something an agent has to REMEMBER. `sb_live_join`
+ * was opt-in and one call, which reads as cheap and is not: an agent that never
+ * makes it builds an entire site the watching merchant cannot see happening —
+ * no peer, no cursor, no element appearing as it lands. Nothing fails, so
+ * nothing prompts the question, and the person who asked for an agent watches a
+ * static canvas and concludes it is not working.
+ *
+ * Measured here: one session built 17 pages and 19 products over two hours with
+ * an editor open beside it and never joined.
+ *
+ * `PageSession.ensureLive` calls this on the first page open, which is where
+ * designing starts. The explicit tool stays, for a caller who wants to join a
+ * different site or re-join after a drop.
+ */
+export function joinRoom(ctx, session, siteId) {
+    const tokenFn = liveTokenFor(ctx);
+    const wsBase = ctx.base.replace(/^http/, 'ws').replace(/\/$/, '');
+    const socket = new RealtimeSocket(`${wsBase}/api/realtime/ws?site=${encodeURIComponent(siteId)}`, tokenFn);
+    const live = new LiveSession(socket, {
+        onRemote: (patches) => session.applyRemote(patches),
+        onDesync: (reason) => session.markStale(reason),
+    });
+    socket.connect();
+    session.attachLive(live);
+}
 export function registerLiveTools(server, ctx, session) {
+    // The page session joins on its own at the first sb_page_open. Registered
+    // here because this module owns the socket and the session must not import it.
+    session.setLiveJoiner((siteId) => joinRoom(ctx, session, siteId));
     server.registerTool('sb_live_join', {
         description: "Join the site's live-edit room as a visible peer: every write then appears in any open " +
             'editor as it happens, with the agent shown by the API key\'s own name rather than a ' +
@@ -218,15 +249,7 @@ export function registerLiveTools(server, ctx, session) {
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
     }, async ({ site_id: given }) => {
         const site_id = siteFor(ctx, given);
-        const tokenFn = liveTokenFor(ctx);
-        const wsBase = ctx.base.replace(/^http/, 'ws').replace(/\/$/, '');
-        const socket = new RealtimeSocket(`${wsBase}/api/realtime/ws?site=${encodeURIComponent(site_id)}`, tokenFn);
-        const live = new LiveSession(socket, {
-            onRemote: (patches) => session.applyRemote(patches),
-            onDesync: (reason) => session.markStale(reason),
-        });
-        socket.connect();
-        session.attachLive(live);
+        joinRoom(ctx, session, site_id);
         return text({
             joined: site_id,
             note: 'Edits now publish to the room as they are made. Call sb_page_open next.',

package/dist/tools/page.js

@@ -19,7 +19,7 @@ import { compactFindings } from '../domains/site/findings.js';
 import { readinessGaps, READINESS_NOTICE } from '../domains/site/readiness.js';
 import { gatherReadiness } from '../domains/site/readiness-fetch.js';
 import { globalWarning, restampPatches, RESPONSIVE_NOTICE } from '../domains/site/traps.js';
-import { catalogMatches, traitsFor } from '../catalog/element-search.js';
+import { catalogBrowse, catalogMatches, traitsFor } from '../catalog/element-search.js';
 import { LAYOUT_PATTERNS, PATTERN_BY_ID, THEME_TOKENS, } from '../domains/site/patterns.js';
 import { tokensFromPage } from '../domains/site/importmap.js';
 import { middleEnd } from '../domains/site/traps.js';
@@ -67,6 +67,8 @@ export class PageSession {
      * fence `restampPatches` exists to keep honest.
      */
     savedRev = -1;
+    /** The open read handed back an empty document and a ROOT was invented for it. */
+    openedSeeded = false;
     warnings = [];
     boxes = [];
     constructor(ctx) {
@@ -75,6 +77,49 @@ export class PageSession {
     attachLive(live) {
         this.live = live;
     }
+    /**
+     * How to open the live-edit room, handed over by `registerLiveTools`.
+     *
+     * A CALLBACK rather than an import, because `live.ts` already imports this
+     * class and the reverse edge would be a cycle. The direction that matters is
+     * the one the design has: the room knows about the page session, not the other
+     * way round.
+     */
+    liveJoiner = null;
+    setLiveJoiner(fn) {
+        this.liveJoiner = fn;
+    }
+    /**
+     * JOIN BEFORE THE FIRST EDIT, rather than when an agent remembers to.
+     *
+     * `sb_live_join` is one call and reads as cheap, which is exactly why it gets
+     * skipped: nothing fails without it. The room is simply empty, so a merchant
+     * watching their own site being built sees a static canvas and concludes the
+     * agent is not working. Measured here — one session built 17 pages and 19
+     * products over two hours with an editor open beside it and never joined.
+     *
+     * Opening a page is where designing starts, so that is where this fires. The
+     * room ALWAYS YIELDS to a human (see the yield rule), so joining early costs
+     * a socket and risks nothing.
+     *
+     * FAILURE IS NOT FATAL. No credential, no network, a server without the
+     * endpoint — none of those are reasons to refuse to open a page. The caller is
+     * told, and goes on designing with nobody watching, which is the old behaviour
+     * rather than a new one.
+     */
+    async ensureLive(siteId) {
+        if (this.live)
+            return 'already';
+        if (!this.liveJoiner)
+            return 'no live transport is registered';
+        try {
+            this.liveJoiner(siteId);
+            return this.live ? 'joined' : 'the live transport did not attach';
+        }
+        catch (e) {
+            return e.message.replace(/^sbuilder:\s*/, '').slice(0, 160);
+        }
+    }
     location() {
         this.current();
         return { siteId: this.siteId, pageId: this.pageId };
@@ -126,6 +171,19 @@ export class PageSession {
      */
     async applyAndSave(patches) {
         const d = this.current();
+        // EVERY WRITE CHECKS THE ROOM, not only the first page open.
+        //
+        // Joining once at open is right until the once fails. No network for a
+        // moment, a credential that arrived late, a server that had not brought the
+        // endpoint up yet — any of those leave a session that edits for an hour with
+        // nobody watching and no second attempt, which is the same silence this
+        // whole path exists to end.
+        //
+        // FREE WHEN JOINED: `ensureLive` returns on a null check, so the steady state
+        // costs one branch per write. A dropped socket is NOT this method's problem —
+        // `RealtimeSocket` owns its own reconnect with backoff, and re-attaching a
+        // second LiveSession over a live one would be the bug, not the fix.
+        await this.ensureLive(this.siteId);
         const before = new Set(validateForSave(d));
         const after = validateForSave(d.preview(patches));
         const introduced = after.filter((p) => !before.has(p));
@@ -174,8 +232,24 @@ export class PageSession {
         this.warnings = composeWarnings(src.warnings);
         // Freshly pulled IS the stored state.
         this.savedRev = this.doc.rev;
+        // WHAT THE READ ACTUALLY RETURNED, kept so `save` can tell a page this
+        // session emptied from a page that arrived empty because the read failed
+        // open. `PageDoc.from` seeds a ROOT for `{ root_node_id: "", nodes: {} }`,
+        // which is right for a page just created and catastrophic for one that has
+        // content — and the two are identical bytes, so only the save can judge.
+        this.openedSeeded = this.doc.seededRoot === true;
+        // A PAGE IS NOW ON THE CANVAS, so the room is joined here rather than in the
+        // one tool that happens to be the usual way in. `sb_page_create`,
+        // `sb_template_use` and `shareChrome` all open pages too, and a join wired to
+        // sb_page_open alone leaves every one of those editing unseen.
+        this.liveState = await this.ensureLive(siteId);
         return this.doc.outline();
     }
+    /** What the last open's join attempt did, for the tool that reports it. */
+    liveState = 'already';
+    liveStatus() {
+        return this.liveState;
+    }
     /** What the server said it could not compose when this page was opened. */
     composeWarnings() {
         return this.warnings;
@@ -245,6 +319,48 @@ export class PageSession {
         if (problems.length > 0) {
             throw new Error(`sbuilder: refusing to save — ${problems.join(' ')}`);
         }
+        // A READ THAT FAILED OPEN MUST NOT BECOME A WRITE THAT EMPTIES THE PAGE.
+        //
+        // `PageDoc.from` seeds a ROOT when the source comes back
+        // `{ root_node_id: "", nodes: {} }`. For a page the caller has just created
+        // that is the whole point. For a page that HAS content it is a blank tree
+        // this session now believes is the page, and the first save stores it over
+        // whatever the server holds — silently, because every later gate agrees a
+        // bare ROOT is a valid document.
+        //
+        // MEASURED, not reasoned about. A product template carrying 24 nodes plus a
+        // shared header and footer came back bare to one session and was stored
+        // bare. The PUBLISHED copy was untouched, so all 19 product pages kept
+        // rendering while the draft the editor opens was blank; the damage was
+        // invisible until a person opened the page, and one publish from that draft
+        // would have taken every one of those 19 down at once.
+        //
+        // So when the read was seeded, this asks the server what it actually holds
+        // before writing. The round trip is paid ONLY here — a seeded read is the
+        // first save of a new page or this bug, and nothing else. A page the server
+        // also reports as empty is genuinely new and the write goes through.
+        //
+        // Refusing rather than re-pulling and merging: the session cannot know which
+        // of its edits belong on the real tree, and a merge that guesses is how a
+        // caller ends up with a page that is neither what it built nor what was
+        // there. The caller re-opens and reapplies, which is the yield rule's answer
+        // to every other divergence and is already the reflex these tools teach.
+        if (this.openedSeeded) {
+            const stored = await loadSource(this.ctx, this.siteId, this.pageId);
+            const held = (stored.document ?? {});
+            const heldCount = Object.keys(held.nodes ?? {}).length;
+            if (heldCount > 0) {
+                this.openedSeeded = false;
+                await this.open(this.siteId, this.pageId);
+                throw new Error(`sbuilder: refusing to save — this page was read as EMPTY and a ROOT was invented for ` +
+                    `it, but the server holds ${heldCount} node(s). Writing would have erased the page. ` +
+                    'It has been re-loaded from the server; re-read it with sb_outline and reapply your ' +
+                    'change.');
+            }
+            // The server agrees the page is empty, so the seeded ROOT is this page's
+            // first real tree and every save after this one is an ordinary save.
+            this.openedSeeded = false;
+        }
         const saved = await saveSource(this.ctx, this.siteId, this.pageId, d.doc);
         // RE-STAMP THE FENCE, or lose every edit after this one.
         //
@@ -377,6 +493,8 @@ export function registerPageTools(server, ctx) {
         annotations: { readOnlyHint: true },
     }, async ({ site_id: given, page_id }) => {
         const outline = await session.open(siteFor(ctx, given), page_id);
+        // `open` joined the room on the way through — this only reports what it did.
+        const live = session.liveStatus();
         const doc = session.current();
         // A page whose stored document named its root under the app-block key
         // renders as an empty <body> and says nothing about why. Nobody else can
@@ -386,10 +504,28 @@ 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;
+        // AN EMPTY READ IS REPORTED, because the caller is the only one who knows
+        // whether this page is supposed to be empty. A page just created reads
+        // this and carries on; a page that was built reads it and stops — which is
+        // the whole difference between noticing now and noticing after a publish.
+        const seeded_empty = doc.seededRoot
+            ? 'This page came back EMPTY and a ROOT was seeded for it. That is expected for a page ' +
+                'you just created. If this page HAD content, do not edit or publish it — the draft ' +
+                'read is blank, not the page: re-open it, and if it is still blank restore it from ' +
+                'GET /api/sites/{siteId}/pages/{pageId}/history.'
+            : undefined;
         const warnings = session.composeWarnings();
         return text({
             outline,
+            // Said ONLY when it is news. 'already' is the steady state after the
+            // first open and repeating it on every page is the shape that drifts.
+            ...(live === 'joined'
+                ? { live: 'Joined the live-edit room — anyone with this site open sees these edits as they land.' }
+                : live === 'already'
+                    ? {}
+                    : { live_unavailable: live }),
             ...(blank_page_repair ? { blank_page_repair } : {}),
+            ...(seeded_empty ? { seeded_empty } : {}),
             ...(warnings.length ? { compose_warnings: warnings } : {}),
             ...reviewField(ctx, doc),
         });
@@ -420,15 +556,29 @@ export function registerPageTools(server, ctx) {
         return text({ node, ...(preset ? { preset } : {}), ...(warn ? { warning: warn } : {}) });
     });
     server.registerTool('sb_catalog_search', {
-        description: 'Find an element type by what you want it to do. Four fields per match; pass detail:true ' +
-            "for the platform's AI hints, or read them with sb_traits_for once you have chosen.",
+        description: 'Find an element type by what it does — or OMIT query to browse every type, the only ' +
+            'way to meet one you would not have searched for. detail:true adds the AI hints, as ' +
+            'does sb_traits_for.',
         inputSchema: {
-            query: z.string(),
-            limit: z.number().int().min(1).max(30).optional().describe('Default 8'),
+            query: z.string().optional(),
+            limit: z.number().int().min(1).max(60).optional().describe('Default 8'),
             detail: z.boolean().optional().describe('Include useWhen / avoidWhen / contentTips per match'),
         },
         annotations: { readOnlyHint: true },
-    }, async ({ query, limit, detail }) => text(catalogMatches(query, { limit, detail })));
+    }, 
+    // A SEARCH CANNOT INTRODUCE YOU TO ANYTHING. Omitting the query browses the
+    // whole catalogue instead — see catalogBrowse for the measurement that made
+    // this necessary: a store built with these tools used 17 element types and
+    // hand-assembled what a dozen purpose-built ones already do.
+    async ({ query, limit, detail }) => text(query && query.trim()
+        ? catalogMatches(query, { limit, detail })
+        : {
+            elements: catalogBrowse(),
+            note: 'Every element type, grouped as the palette groups them. Pass a TYPE as query ' +
+                'for the fields to choose by, or a CATEGORY NAME with limit 60 to read that ' +
+                "whole group's descriptions at once — which is how you find out what the ones " +
+                'you have never used are for. sb_traits_for then has the controls and hints.',
+        }));
     server.registerTool('sb_traits_for', {
         description: "This element's INSPECTOR, as a person sees it: tabs, groups, and every control name — " +
             'with what each DECLARED control writes, and the AI hints for using the element. Read ' +

package/dist/tools/session.js

@@ -34,6 +34,22 @@ export async function connect(ctx, args) {
                     'pass that site id to sb_page_open, or set SB_SITE once and leave site_id out. Set ' +
                     'SB_EMAIL and SB_PASSWORD as well if you want account-level calls (listing sites, ' +
                     'members, roles), which a key cannot make.',
+            // SAID HERE BECAUSE HERE IS WHERE IT IS STILL FREE.
+            //
+            // `sb_live_join` is opt-in and one call, and an agent that never makes it
+            // builds an entire site the watching merchant cannot see happening: no
+            // peer in the room, no cursor, no element appearing as it lands. Nothing
+            // fails, so nothing prompts the question — the room is simply empty, and
+            // the person who asked for an agent watches a static canvas and concludes
+            // the agent is not working.
+            //
+            // MEASURED: one session built 17 pages and 19 products over two hours with
+            // an editor open beside it and never joined, because no surface an agent
+            // reads on the way in mentions the room. The tool's own description says
+            // what it does; nothing said WHEN. Connect is that when.
+            live: 'Nobody watching an open editor sees these edits until sb_live_join is called. Call it ' +
+                'now if a person has the site open — it takes this key\'s own name, always yields to a ' +
+                'human, and is safe to leave on for the whole session.',
         };
     }
     if (!email || !password) {

package/package.json

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