@bettercms-ai/mcp 0.30.0 → 0.31.2

package/dist/index.js

@@ -2485,6 +2485,10 @@ function buildToolDefs(deps) {
     command: layoutCommand.describe("one canonical discriminated Layout command; authority is derived from type"),
     ifMatch: z.number().int().nonnegative().describe("revision returned by get_layout")
   });
+  const publishLayoutInput = z.object({
+    projectId: z.string().min(1).optional().describe("required only for a workspace-scoped grant"),
+    ifMatch: z.number().int().nonnegative().describe("revision returned by get_layout (scope global)")
+  });
   const componentCategory = z.enum([
     "navbar",
     "footer",
@@ -2833,8 +2837,8 @@ function buildToolDefs(deps) {
       def(
         "update_project",
         "Update the connected project",
-        "Update the connected project's settings \u2014 rename it, change its slug/description, SEO defaults, or visibility. Only the provided fields change.",
-        z.object({ name: z.string().optional(), slug: z.string().optional(), description: z.string().optional(), visibility: z.string().optional(), seoDefaults: z.record(z.string(), z.unknown()).optional() }).shape,
+        "Update the connected project's settings \u2014 rename it, change its slug/description, SEO defaults, visibility, or `presentation`. Only the provided fields change. `presentation` themes the platform's OWN renderer (the one serving a site built in the CMS with no deployed build, and previewing structural drafts everywhere) with the same closed knobs as bcms-presentation.json \u2014 DTCG { $type, $value } tokens keyed like 'page.maxWidth', 'nav.background'. Without it that renderer is a generic 768px document theme. An invalid manifest is 422 PRESENTATION_INVALID.",
+        z.object({ name: z.string().optional(), slug: z.string().optional(), description: z.string().optional(), visibility: z.string().optional(), seoDefaults: z.record(z.string(), z.unknown()).optional(), presentation: z.record(z.string(), z.unknown()).optional().describe("theme knobs for the platform renderer, keyed like bcms-presentation.json") }).shape,
         async (c, a) => ok("Updated project.", await data(c, "PATCH", `/management/projects/current`, a))
       ),
       def(
@@ -2961,7 +2965,7 @@ function buildToolDefs(deps) {
       def(
         "deploy_project",
         "Deploy new source/build",
-        "Deploy new source/build for the connected project and make it live at its <handle>.bettercms.site. Pass a .tgz or .zip of the project as a base64 string in `data`: SOURCE (has package.json) is built server-side in an isolated sandbox; a prebuilt static site is served as-is. Returns the release id + sha \u2014 then poll get_deploy_status until it is live. IMPORTANT \u2014 you MUST exclude node_modules, .git, and build output/caches (dist, build, .next, .astro, .cache) BEFORE creating the archive: a source deploy is reinstalled and built server-side, so those are never needed, and the upload has a hard size ceiling (~100 MB) enforced before the request reaches the server \u2014 an archive that includes node_modules is rejected in transit (a 413/502 with no server-side detail). Keep the archive to your own source files. Server-side stripping exists as a safety net, but it runs AFTER the upload and cannot rescue an over-limit body. For a LARGE archive (or if this returns a 413/502), use create_deploy_upload + deploy_from_upload instead \u2014 that path uploads straight to storage with no size ceiling.",
+        "Deploy new source/build for the connected project and make it live at its <handle>.bettercms.site. Pass a .tgz or .zip of the project as a base64 string in `data`: SOURCE (has package.json) is built server-side in an isolated sandbox; a prebuilt static site is served as-is. Returns the release id + sha \u2014 then poll get_deploy_status until it is live. IMPORTANT \u2014 you MUST exclude node_modules, .git, and build output/caches (dist, build, .next, .astro, .cache) BEFORE creating the archive: a source deploy is reinstalled and built server-side, so those are never needed, and the upload has a hard size ceiling (~100 MB) enforced before the request reaches the server \u2014 an archive that includes node_modules is rejected in transit (a 413/502 with no server-side detail). Keep the archive to your own source files. Server-side stripping exists as a safety net, but it runs AFTER the upload and cannot rescue an over-limit body. For a LARGE archive (or if this returns a 413/502), use create_deploy_upload + deploy_from_upload instead \u2014 that path uploads straight to storage with no size ceiling. Returns `canvas.lane` \u2014 which live-preview lane the last release gave the editor (`bridge` / `draft-route` / `none`; see the playbook's section 11) \u2014 and `editorUrl`, the visual editor to hand the user.",
         z.object({ data: z.string().min(1).describe("base64 .tgz/.zip of the project"), mimeType: z.string().optional() }).shape,
         async (c, a) => ok("Deploy queued.", await raw(c, `/management/projects/deploy`, s(a.data), a.mimeType))
       ),
@@ -3004,7 +3008,7 @@ function buildToolDefs(deps) {
       def(
         "get_binding_report",
         "Check what on the live site is editable",
-        "The receipt for 'is this site actually EDITABLE?'. Every release scans the built HTML for the element that renders each CMS field value; this returns what that scan found, per slot: `mode` ('text-match' = bindings guessed from rendered text, 'declared' = the template declares them), `pagesInspected`, `bound` (elements carrying a binding), and `unmatched` \u2014 per page, each path with its kind and the reason it failed (not-declared / ambiguous-text / no-element). DEPLOY FIRST: before any release there is no report and this answers pages 0, mode null, refreshRequired true. It certifies exactly one thing \u2014 that every non-empty field of every page has SOME element carrying its path. It cannot see copy that was never modelled, so diff each route's visible text against its entry values yourself before calling a page done. Pass `slot` ('current' or 'staging') to read the other tree; the default is the slot this project's releases land in.",
+        "The receipt for 'is this site actually EDITABLE?'. Every release scans the built HTML for the element that renders each CMS field value; this returns what that scan found, per slot: `mode` ('text-match' = bindings guessed from rendered text, 'declared' = the template declares them), `pagesInspected`, `bound` (elements carrying a binding), and `unmatched` \u2014 per page, each path with its kind and the reason it failed (not-declared / ambiguous-text / no-element). DEPLOY FIRST: before any release there is no report and this answers pages 0, mode null, refreshRequired true. It certifies exactly one thing \u2014 that every non-empty field of every page has SOME element carrying its path. It cannot see copy that was never modelled, so diff each route's visible text against its entry values yourself before calling a page done. `builtRoutes` lists the routes the live build has HTML for (null when unknown: runtime release, >500 routes, or a report older than this field). `canvas.lane` names the live-preview lane this build gives the editor \u2014 `bridge` (the build ships BcmsDraftBridge), `draft-route` (a node runtime rendering drafts server-side) or `none`, in which case get_next_steps carries the recipe (playbook section 11); null means the report predates the field. `unaddressable` counts visible text on the live site that no field owns, as the editor's x-ray measured it against the sha now serving \u2014 the one thing `unmatched` structurally cannot see; absent means nobody has turned that control on for this build. `unaddressable` is measured PER SLOT by the editor, which frames `current`; on a promote-gated project pass slot:'current' to read it. Pass `slot` ('current' or 'staging') to read the other tree; the default is the slot this project's releases land in.",
         z.object({ slot: z.enum(["current", "staging"]).optional().describe("which release tree to read; defaults to the one this project deploys to") }).shape,
         async (c, a) => ok("Binding report.", await data(c, "GET", `/management/projects/current/binding-report${q({ slot: a.slot })}`))
       ),
@@ -3214,7 +3218,7 @@ function buildToolDefs(deps) {
       def(
         "get_deploy_status",
         "Get deploy/build status",
-        "Get the connected project's deploy/build status: state (idle|queued|building|failed), whether it's publishing, the live commit sha, when it went live, and any build error. Poll this after deploy_project until state is idle with your sha live.",
+        "Get the connected project's deploy/build status: state (idle|queued|building|failed), whether it's publishing, the live commit sha, when it went live, and any build error. Poll this after deploy_project until state is idle with your sha live. Also returns `canvas.lane` (the editor's live-preview lane for this site: `bridge` / `draft-route` / `none`) and `editorUrl`, the visual editor to hand the user.",
         z.object({}).shape,
         async (c) => ok("Deploy status.", await data(c, "GET", `/management/projects/deploy-status`))
       )
@@ -3565,7 +3569,7 @@ function buildToolDefs(deps) {
         })
       )
     },
-    // ── Project/page Layout (draft-only; publish remains dashboard-gated) ──
+    // ── Project/page Layout (draft commands + Global Layout publish; page overrides publish with the page) ──
     {
       name: "get_layout",
       config: {
@@ -3590,6 +3594,18 @@ function buildToolDefs(deps) {
         return ok(`Updated ${layout.scope === "global" ? "Global" : `Page ${layout.pageSlug}`} Layout draft to revision ${layout.revision}.`, layout);
       }))
     },
+    {
+      name: "publish_layout",
+      config: {
+        title: "Publish the Global Layout draft",
+        description: "Publish the connected project's GLOBAL Layout draft (navigation, footer, every reserved section) so the live site builds from it. Until this is called the layout stays draft and get_layout copy:'published' answers PUBLISHED_LAYOUT_UNAVAILABLE \u2014 site chrome authored with update_layout is NOT live. Read get_layout first and pass its revision as ifMatch; a stale revision returns 409 \u2014 re-read, never retry blindly. A 422 lists validation issues to fix with update_layout first. Verify with get_layout copy:'published' and check the copy echo \u2014 this tool's own response is the write's echo, not a receipt. Page overrides go live with the page (update_page status:'published'). A 403 PUBLISH_NOT_GRANTED means this connection can author drafts but cannot publish \u2014 say so and let the user allow publishing or publish from the dashboard.",
+        inputSchema: publishLayoutInput.shape
+      },
+      handler: guard(async (args) => withClient(async (client) => {
+        const layout = await client.publishManagedLayout(args);
+        return ok(`Published the Global Layout at revision ${layout.revision} (copy: published). Verify with get_layout copy:'published'.`, layout);
+      }))
+    },
     // ── Components (discover + author reusable symbols) ──
     {
       name: "list_components",
@@ -3788,9 +3804,11 @@ Decide before your first call; converting later means rewriting content.
 
 ## 3. Anatomy of a real section component
 
-A component that is only headings and text renders as an unstyled stack. Every section the
-product ships looks like this \u2014 a \`section\` block carrying \`style\`, with content nested in
-\`props.children\`:
+A component that is only headings and text renders as an unstyled stack \u2014 plain text on white
+in a 768px column, on the live site AND in the visual editor. Every section the product ships
+looks like this \u2014 a \`section\` block carrying \`style\`, with content nested in
+\`props.children\`. \`create_component\` and \`update_component\` return a \`warnings\` entry when a
+Section's root section has no \`style\`; treat it as a defect, not a note:
 
     {
       type: "section", id: "root",
@@ -3845,8 +3863,8 @@ words (the page-builder model): each placement takes that group's current values
 kept and marked \`origin: "componentized"\` so the editor stops offering a second place to type
 them. Either way, running it again converts nothing and duplicates nothing. Then run \`npx @bettercms-ai/convert --componentize\` in the repo
 so its templates render those sections from \`pages[].blocks\`, and finish with the publishes:
-\`publish_component\` every new component and publish the pages, or the site renders the
-sections as empty strings.
+\`publish_component\` every new component, \`publish_layout\` if you touched site chrome (nav,
+footer), and publish the pages, or the site renders the sections as empty strings.
 
 ## 5. Blocks and modular fields
 
@@ -3911,6 +3929,7 @@ is interpolated per entry with \`{{fieldKey}}\` placeholders \u2014 \`{{title}}\
     5. pages        create_page with blockJson placing those components
     6. content      create_content_entry / set_page_content
     7. publish      update_page status:'published'
+    7b. layout      publish_layout  <- if you authored the Global Layout (nav/footer); page overrides publish with the page
     8. check        get_next_steps, and fix what it lists
 
 ## 8. Two ways to ship a blank site
@@ -3930,8 +3949,11 @@ in preview and is blank in production. Always pass the project's id.
 accepts it and ignores it**, silently. No error, no warning, wrong project.
 
 So call \`get_project\` (no arguments) first \u2014 it reports the project you are actually
-writing to. If that is not where the work belongs, stop and tell the user: only they can
-approve a grant for the other project, no tool can switch it.
+writing to. If that is not where the work belongs \u2014 or it answers that the grant covers the
+whole workspace \u2014 stop and tell the user the one-step fix: in the BetterCMS dashboard open
+**Settings \u2192 Connected AI clients** and use **Scope to project** on this connection. No tool
+can switch it, but the user does NOT need to re-authorize or re-add the server: the next call
+after that runs with the new scope. Then retry.
 
 If you must probe, probe with a \`create_content_model\` \u2014 models are deletable
 (\`delete_content_model\`, soft-delete) and **there is no \`delete_component\`**. A component
@@ -3957,10 +3979,15 @@ in this order:
 
     1. create_component      per section (they land as DRAFTS)
     2. publish_component     each one \u2014 unpublished renders as NOTHING, on a page that 200s
+    2b. publish_layout       if you authored site chrome \u2014 the layout is a separate publish
     3. set_page_content      place them as \`component\` blocks on the page
     4. list_extraction_candidates / extract_component
                              now that blocks exist, fold any section repeated 3+ times
 
+Step 2 is not a formality: \`componentize_sections\` and \`create_component\` both land components
+as DRAFTS, so \`publish_component\` each one and publish the page \u2014 otherwise the canvas keeps
+painting the PUBLISHED copy and the editor reports N components unpublished.
+
 **Answering \`fields\` is a real answer, not a deferral.** A blog, a catalogue or a directory
 is schema-first by design (\xA71) and should stay that way. Say so and move on.
 
@@ -3973,16 +4000,45 @@ the user rather than describing the choice in the abstract.
 A deploy makes a site LIVE. It does not make it editable \u2014 those are different states, and the
 gap between them is the single most common disappointment after an import.
 
-**The canvas is the real site when it can be.** When a page's draft matches its published copy
-structurally, the visual editor frames the project's OWN deployed build and paints unpublished
-text over it. Structural drafts (new sections, unpublished pages, changed components) render on
-the platform's own renderer instead \u2014 and that renderer previews in a GENERIC theme unless the
-deploy artifact declares \`bcms-presentation.json\` at its root. Put the file in \`public/\`
+**The canvas is the real site.** A PUBLISHED page of a DEPLOYED site with DECLARED bindings
+frames the project's OWN build, with unpublished text painted over it, whether or not the draft
+has drifted from the published copy. STRUCTURAL drafts (new
+sections, reordering, a changed component definition) are the one thing that build cannot show,
+and there are four ways to see them: publish and redeploy; the editor's **Draft render** toggle,
+which swaps in the platform renderer on demand (approximate theme, one click back); live, through
+the draft bridge below (Next); or \u2014 for server-rendered sites \u2014 the node lane, coming.
+
+Only FOUR states use the platform renderer by default: an UNPUBLISHED page, a page whose route
+the last build does not carry (\`get_binding_report.builtRoutes\`), a project with NO build at
+all, and a \`mode: "text-match"\` site whose draft has drifted (its elements are found by matching
+page text to stored values, so drifted text may be unclickable \u2014 declare the bindings, \xA713).
+Those are exactly where \`bcms-presentation.json\` matters \u2014 the renderer previews in a
+GENERIC theme unless the deploy artifact declares one at its root. Put the file in \`public/\`
 (the build lands it at the artifact root) declaring the site's presentation \u2014 container width,
 type scale, nav position and background, footer surface \u2014 as DTCG \`{"$type": ..., "$value": ...}\`
 entries. Redeclare it on every deploy; absent means "declared nothing" and previews fall back
 to platform defaults that will not look like this site.
 
+**Which live-preview lane THIS site has, and what it costs not to have one.**
+\`get_binding_report.canvas.lane\` names it: \`bridge\` (the build ships \`BcmsDraftBridge\` from
+\`@bettercms-ai/next/draft-bridge\`, so a structural draft re-renders inside the site's own
+build), \`draft-route\` (a node runtime whose app renders drafts server-side), or \`none\` \u2014 no
+lane, so every structural draft falls back to the platform renderer and its generic theme.
+\`null\` means the report predates the field; redeploy to learn. When it is \`none\`,
+\`get_next_steps\` names the recipe for this project's framework (\`canvas-lane-missing\`), and
+\xA713 step 5c has both. The same report carries \`unaddressable\`: how much VISIBLE text on the
+live site no field owns, counted against the sha now serving when an author turns the visual
+editor's **"Unbound text"** control on \u2014 \`unmatched\` cannot see it, because it only ever speaks
+about fields that already exist. Absent means nobody has turned that control on for this build,
+not that the site is clean.
+
+**A site built in the CMS with NO deployed build has only that renderer** \u2014 live and in the
+editor \u2014 so the generic theme IS the site until you theme it. Theme it without a deploy:
+\`update_project { presentation: { "page.maxWidth": { "$type": "dimension", "$value": 1200 },
+"nav.background": { "$type": "color", "$value": "#0b0b0b" }, ... } }\` takes the same knobs as
+bcms-presentation.json, and set \`style\` on every Section's root (\xA73). A later deploy that
+ships bcms-presentation.json replaces it wholesale.
+
 **Editing binds by VALUE.** The editor matches CMS field values against the text the site
 renders. Three consequences, each load-bearing:
 
@@ -3995,6 +4051,7 @@ renders. Three consequences, each load-bearing:
          c. set_page_content       values EXACTLY equal to the text the site renders \u2014
                                    binding matches by value, so a paraphrase binds nothing
          d. update_page            status 'published' \u2014 the canvas binds the PUBLISHED copy
+         e. publish_layout         if site chrome was authored \u2014 the canvas binds the PUBLISHED layout too
     2. A value that renders in more than one place is still ONE field: bind every element that
        renders it, and the editor keeps them in sync \u2014 an edit patches every copy at once.
        Binding only one copy leaves the others showing the old text until the next rebuild.
@@ -4028,13 +4085,14 @@ renders. Three consequences, each load-bearing:
        content. Div-built chrome outside \`<main>\` is still excluded; div-built chrome with no
        \`<main>\` anywhere loses that protection.
 
-**Structural drafts can render on the real site too \u2014 the draft bridge.** Wrap your page's
+**Structural drafts can render on the real site too, LIVE \u2014 the draft bridge.** Wrap your page's
 blocks in \`BcmsDraftBridge\` (\`@bettercms-ai/next/draft-bridge\`) instead of calling
 \`BcmsBlocks\` directly: standalone it renders identically, and inside the visual editor it
 receives the DRAFT block tree over a same-origin postMessage handshake and re-renders it with
 the site's own components \u2014 so adding, removing or reordering sections previews in the site's
-real design instead of the platform's approximate renderer. Sites without the bridge keep the
-approximate fallback; unpublished ROUTES always fall back (a static build has no file to frame).
+real design, with no publish and no Draft render detour. A bridge that answers wins over the
+toggle. Sites without one keep Draft render's approximate fallback, and a route the build does
+not carry falls back always (a static build has no file to frame).
 
 **Hosting decides whether a canvas exists at all.** A site deployed here is framed through a
 same-origin proxy \u2014 that is what the canvas requires. A site hosted elsewhere (your own Vercel,
@@ -4050,7 +4108,8 @@ green on the wrong document. Three rules, none optional:
        the draft; a PUBLISH claim verifies ONLY via \`get_layout copy:'published'\` (or the
        entry/page's published copy) \u2014 and check the response's \`copy\` echo says
        'published'. A reader that ignores your copy selector hands you the draft and a
-       false green; the echo is how you catch it.
+       false green; the echo is how you catch it. \`publish_layout\`'s own response echoes
+       copy:'published' too \u2014 that is the WRITE's echo, not a receipt; still re-read.
     2. Publish and deploy are SEPARATE claims. "Published" means the published copy changed;
        the LIVE SITE changes only after its next deploy/rebuild. Never report "it's live"
        from a publish receipt \u2014 fetch the live URL (cache-busted) for that claim.
@@ -4194,6 +4253,17 @@ conversion is yours to write.
       and no network content step, by design. So the archive MUST SHIP its own
       \`bcms-content.json\` \u2014 generate it locally with a delivery key and commit it. Without
       one the site renders its fallbacks and the report says \`no-element\` for every path.
+5c. **Live preview lane.** Static HTML makes a page click-to-edit; it cannot show a STRUCTURAL
+    draft \u2014 a new section, a reorder, a changed component \u2014 so those fall back to the platform
+    renderer's generic theme unless the build can render drafts itself. Give it a lane:
+    - NEXT: wrap the page's \`BcmsBlocks\` in \`BcmsDraftBridge\` from
+      \`@bettercms-ai/next/draft-bridge\` and redeploy. The bridge marks its output
+      \`data-bcms-canvas="bridge"\`, which is what the release scan records.
+    - ASTRO: switch the pages to \`output: 'server'\` with the node adapter, mount
+      \`@bettercms-ai/astro\`'s draft routes under \`src/pages/api/bcms/draft/\`, set
+      \`BCMS_DRAFT_SECRET\`, redeploy, then switch the project to "Run as a server app" on the
+      Hosting page. Never migrate a static site to SSR without asking the human first.
+    Then \`get_binding_report.canvas.lane\` reads \`bridge\` or \`draft-route\` instead of \`none\`.
 6. Push, or \`deploy_project\`; poll \`get_deploy_status\` until it is live. Then
    \`get_binding_report\` \u2014 still \`text-match\`, and \`unmatched\` should be EMPTY because the
    values are byte-equal to what the build renders. On a converted site read \`coverage\` too: it
@@ -4287,9 +4357,10 @@ error-prone, so go slow and confirm. Never guess the layout.
 6. **\`publish_component\`.** It lands as a DRAFT, and a draft component renders as NOTHING on
    the live site \u2014 no error, no placeholder. This step is not optional.
 `;
-var LAYOUT_FLOW = `### Project/page Layout authoring \u2192 \`get_layout\` / \`update_layout\`
-Edit the project's draft Global Layout or one page's draft override. Layout publishing stays
-in the dashboard; these tools never change the live site.
+var LAYOUT_FLOW = `### Project/page Layout authoring \u2192 \`get_layout\` / \`update_layout\` / \`publish_layout\`
+Edit the project's draft Global Layout or one page's draft override. \`update_layout\` never
+changes the live site; \`publish_layout\` takes the Global Layout draft live (page overrides go
+live with their page). Until it is called, site chrome you authored is NOT on the live site.
 1. **Read first** \u2014 call \`get_layout\` with scope \`global\`, or scope \`page\` + pageId.
    Keep the returned \`revision\`; every write must pass it as \`ifMatch\`.
 2. **Choose one discriminated command type** \u2014 the server derives its authority family;