From e18003d05c7bc0e519acb3643895eb1089d8fd57 Mon Sep 17 00:00:00 2001
From: Daniel Tyack <danieltyack@gmail.com>
Date: Wed, 4 Nov 2026 11:42:38 -0800
Subject: [PATCH] fix(builder): explain when no layout updates are available

---
 components/builder/shell/builder-shell.tsx    |  5 ++++-
 .../rows/BLD-LAYOUT-UPDATE-FEEDBACK.json      | 19 +++++++++++++++++++
 2 files changed, 23 insertions(+), 1 deletion(-)
 create mode 100644 docs/ledger/rows/BLD-LAYOUT-UPDATE-FEEDBACK.json

diff --git a/components/builder/shell/builder-shell.tsx b/components/builder/shell/builder-shell.tsx
index 95f1ba413..b9d1874e1 100644
--- a/components/builder/shell/builder-shell.tsx
+++ b/components/builder/shell/builder-shell.tsx
@@ -302,7 +302,10 @@ export function BuilderShell({ host, brandName, logo, brandAccent, initial, conf
       case 'focus': railDispatch({ type: 'focus', on: !rails.focus }); break
       case 'publish': publish(); break
       case 'add': openAdd(); break
-      case 'update-layouts': if (legacyN) setLayoutsOpen(true); break
+      case 'update-layouts':
+        if (legacyN) setLayoutsOpen(true)
+        else setToast({ say: 'No layout updates are available for this page. Your sections stay as they are.', undo: false })
+        break
       case 'device-desktop': case 'device-tablet': case 'device-phone': dispatch({ type: 'device', device: id.slice(7) as BuilderDevice }); break
       case 'rail-left': case 'rail-right': toggleRail(id === 'rail-left' ? 'left' : 'right'); break
       case 'pin-left': case 'pin-right': railDispatch({ type: 'pin', side: id === 'pin-left' ? 'left' : 'right', pinned: true }); break
diff --git a/docs/ledger/rows/BLD-LAYOUT-UPDATE-FEEDBACK.json b/docs/ledger/rows/BLD-LAYOUT-UPDATE-FEEDBACK.json
new file mode 100644
index 000000000..cfbb82128
--- /dev/null
+++ b/docs/ledger/rows/BLD-LAYOUT-UPDATE-FEEDBACK.json
@@ -0,0 +1,19 @@
+{
+  "id": "BLD-LAYOUT-UPDATE-FEEDBACK",
+  "title": "Explain when the builder page has no available layout updates",
+  "status": "open",
+  "lane": "program",
+  "priority": "P3",
+  "size": "XS",
+  "source": {
+    "file": "components/builder/shell/builder-shell.tsx",
+    "ref": "Daniel November 4 completion audit; root READY production builder observation on e1e2398de"
+  },
+  "detail": "The command bar always offers Update this page to the new layouts, but the handler silently closes it when no sections are eligible. Show a truthful message through the existing polite toast/status region, with no Undo action, document mutation, save or publish. Keep eligible conversion review, per-section choices and one-step Undo unchanged. Bounded acceptance: zero eligible sections yields the message and no sheet/edit; eligible sections still open review; existing conversion/Undo and focus-trap tests remain green. No change to eligibility rules or saved content. Publication checkpoint 2026-11-04: root reviewed the exact two-file source packet; current main e1e2398de is integrated, with no conflicting open builder-shell PR or row reservation. All 26 existing tests, temporary source/status consequence fixture, lint and static guards passed. Publishing for serialized review; preview and production acceptance remain open.",
+  "verify": {
+    "kind": "manual",
+    "checked": "2026-11-04",
+    "evidence": "Root observed a READY production Services page with 13 sections and zero eligible upgrades; the command closed without feedback. Source confirms the command registry has no eligibility requirement and the old handler only opened the sheet for a nonzero count. Local-only candidate adds the existing toast with undo false in the zero branch. Source fixture, focused existing tests, lint and future preview/browser acceptance are tracked separately; this row remains open and no production change is claimed. Local source-extracted handler and actual status-fragment fixture passed zero-eligible, one/many-eligible, pristine silent negative control, no-edit and no-Undo cases. All 26 existing command, conversion, reducer and sheet-focus tests passed; source lint, static backlog, one-list and diff checks passed. No permanent test edits, commit, push or production acceptance."
+  },
+  "wave": "W7"
+}