@bettercms-ai/mcp 0.42.0 → 0.45.0

package/dist/index.js

@@ -1982,6 +1982,126 @@ var LAYOUT_SECTION_ICON_SET = new Set(LAYOUT_SECTION_ICONS);
 // src/tools.ts
 import { BetterCMSError } from "@bettercms-ai/sdk";
 import { DeviceAuthPendingError } from "@bettercms-ai/device-auth";
+
+// src/structure-playbook.ts
+var STRUCTURE_PLAYBOOK_URI = "bettercms://playbook/structure";
+var STRUCTURE_DEFAULT_INSTRUCTION = `After you create collections or pages, organise them per the structure playbook: read ${STRUCTURE_PLAYBOOK_URI}, call suggest_content_structure (read-only), show the user its outline, then apply it with set_content_structure and the version it returned (the If-Match). A project that already has a structure keeps it: file only what you created, with move_to_folder, unless the user asks for a full re-organisation.`;
+var STRUCTURE_EXAMPLE_PAYLOAD = {
+  version: 0,
+  doc: {
+    schema: 1,
+    folders: [
+      { id: "home:pages", parentId: null, name: "Static pages", icon: "files", sort: -3 },
+      { id: "home:collections", parentId: null, name: "Other content", icon: null, sort: -2 },
+      { id: "fld_std_blog", parentId: null, name: "Blog posts", icon: "newspaper", sort: 0 },
+      { id: "fld_std_products", parentId: null, name: "Products", icon: "shopping-bag", sort: 1 }
+    ],
+    items: [
+      { kind: "page", id: "pg_home", folderId: "home:root", sort: 0, icon: null },
+      { kind: "page", id: "pg_blog", folderId: "home:root", sort: 1, icon: null },
+      { kind: "page", id: "pg_shop", folderId: "home:root", sort: 2, icon: null },
+      { kind: "collection", id: "cm_posts", folderId: "fld_std_blog", sort: 0, icon: null },
+      { kind: "collection", id: "cm_products", folderId: "fld_std_products", sort: 0, icon: null },
+      { kind: "collection", id: "cm_categories", folderId: "fld_std_products", sort: 1, icon: null },
+      { kind: "collection", id: "cm_colours", folderId: "fld_std_products", sort: 2, icon: null },
+      { kind: "collection", id: "cm_tags", folderId: "home:collections", sort: 0, icon: null },
+      { kind: "page", id: "pg_about", folderId: "home:pages", sort: 0, icon: null },
+      { kind: "page", id: "pg_contact", folderId: "home:pages", sort: 1, icon: null },
+      { kind: "page", id: "pg_404", folderId: "home:pages", sort: 2, icon: "file-code" }
+    ]
+  }
+};
+var STRUCTURE_PLAYBOOK = `# Organising a BetterCMS project: the Content structure standard
+
+Read this BEFORE you organise the Content sidebar, and AFTER you create collections or pages:
+the default is to organise what you made by these rules. The sidebar is one document per
+project, \`{ schema: 1, folders: [{ id, parentId, name, icon, sort }], items: [{ kind: 'page' |
+'collection', id, folderId, sort, icon }] }\`, read with \`get_content_structure\` and written with
+\`set_content_structure\`. It is ORGANISATION ONLY: no URL, slug, schema, content or publish state
+ever changes.
+
+## The rules
+
+1. **One place per document.** Every page and every collection sits in exactly ONE place: pinned
+   at the top level (\`folderId: "home:root"\`) or in one folder. A folder lists only its direct
+   contents. Never list an id twice.
+2. **Pinned at the top:** the home page, then each collection's LIST page (the dynamic page that
+   lists it, e.g. /blog). A single document opens straight into the editor, so it is a pin, not a
+   folder with one page in it.
+3. **One folder per content family.**
+   - Blog: a "Blog posts" folder holding the blog collection. A folder with exactly one
+     collection opens that collection's table directly.
+   - Commerce: a "Products" folder holding the product collection AND its taxonomies (product
+     categories, product tags, materials, colours, sizes, merch collections, ...).
+   - Decide the rest by the REFERENCE GRAPH: a collection that is referenced only by one family,
+     or that references only one family (reviews \u2192 products), belongs in that family's folder.
+     The family's main collection comes first, then the others in the order its fields reference
+     them.
+4. **Other pages.** Standalone static pages go in the system folder \`home:pages\` ("Static
+   pages"). Code-only routes (a 404, a page built by code with nothing to edit) stay there too,
+   marked with the \`file-code\` icon. Pages that share a route (/legal/terms, /legal/privacy) get
+   a subfolder of Static pages; a large route family or one named for what it is (/docs/...) gets
+   its own top-level folder.
+5. **Shared taxonomies.** A vocabulary several families reference (Tags used by posts AND
+   products) goes in the system folder \`home:collections\`, named "Other content". So does
+   supporting content no family owns (testimonials, FAQs with no list page).
+6. **Icons** (lucide names): \`newspaper\` for posts, \`shopping-bag\` for products, \`book-open\`
+   for docs, \`files\` for Static pages, \`folder\` by default.
+7. **Depth:** nest at most 2 levels by default. The hard limit is 4; do not use it without a
+   reason the user gave you.
+8. **Organisation only.** Never rename a page, change a slug, touch a schema or move content to
+   make a structure fit. The structure fits the site, not the other way round.
+9. **Page-bound models are not collections.** A page with fields has a content model bound to
+   it; it is never filed (400 \`NAV_PAGE_BOUND_MODEL\`). Organise the PAGE.
+
+## The workflow
+
+1. \`get_content_structure\` \u2014 note \`version\` and whether a structure exists.
+2. \`suggest_content_structure\` \u2014 READ-ONLY. It runs the platform's own implementation of these
+   rules over the project's pages, collections, references and routes and returns
+   \`{ doc, outline, rationale, version, hasDocument }\`. It writes nothing.
+3. Show the user the \`outline\`. If \`hasDocument\` is true the project ALREADY has a structure
+   someone made: never replace it without the user's explicit yes. Offer to file only what is
+   new (\`move_to_folder\` per item) instead.
+4. Apply with \`set_content_structure { doc, version }\`, where \`version\` is the one you read \u2014
+   it is the If-Match. A 412 \`VERSION_CONFLICT\` means someone changed the sidebar since: read it
+   again and re-apply; never overwrite blind.
+5. For one or two new documents, prefer \`move_to_folder\` into the matching family folder.
+
+Projects imported from GitHub get this structure automatically (the "Organising your content"
+step of the import), but only when they have none yet; a later import files NEW documents into
+the matching folder and changes nothing else.
+
+## Worked example: a blog plus a shop
+
+The site: a home page (\`pg_home\`), a /blog list page (\`pg_blog\`, dynamic) for the Blog
+collection (\`cm_posts\`), a /shop list page (\`pg_shop\`, dynamic) for Products
+(\`cm_products\`), About (\`pg_about\`), Contact (\`pg_contact\`) and a code-only 404
+(\`pg_404\`). Products references Product categories (\`cm_categories\`) and Colours
+(\`cm_colours\`); both Blog and Products reference Tags (\`cm_tags\`).
+
+\`\`\`text
+[pinned page] Home
+[pinned page] Blog            (/blog lists Blog)
+[pinned page] Shop            (/shop lists Products)
+[system folder] Static pages  icon=files
+  About, Contact, Not found (icon=file-code)
+[system folder] Other content
+  Tags                        (referenced by Blog AND Products: shared)
+[folder] Blog posts           icon=newspaper
+  Blog
+[folder] Products             icon=shopping-bag
+  Products, Product categories, Colours   (referenced only by Products)
+\`\`\`
+
+The exact \`set_content_structure\` payload (\`version: 0\` because the project had no structure):
+
+\`\`\`json
+${JSON.stringify(STRUCTURE_EXAMPLE_PAYLOAD, null, 2)}
+\`\`\`
+`;
+
+// src/tools.ts
 var FRAMEWORK_CHOICES = ["astro", "next", "react-ts", "other"];
 var FRAMEWORK_LABELS = {
   astro: "Astro \u2014 recommended default, static by default and fastest to publish",
@@ -2273,6 +2393,11 @@ function toField(f) {
     ...f.config ? { config: f.config } : {}
   };
 }
+var STRUCTURE_NOTE = 'ORGANISATION ONLY: folders never change a URL, slug, content or publish state, and nothing is rebuilt or delivered. Folders nest at most 4 levels deep (a page or collection may sit in a level-4 folder). Icons are lucide icon names, e.g. "folder", "file-text", "rows-3", "house" (a-z, 0-9 and dashes); null clears one. SYSTEM FOLDERS (CPO-129): "home:pages" (Static pages), "home:collections" (Collections) and "home:globals" (Globals) always exist, even when the document has no record for them. They stay at the top level and can never be moved or deleted (400 NAV_SYSTEM_FOLDER), but rename_folder and set_icon work on them and create their record on first use. TYPE PURITY: anything inside Static pages, at any depth, must be a page, and anything inside Collections must be a collection, and Globals holds NO pages or collections at all, because globals are not sidebar items (subfolders under Globals are allowed but stay empty). Any of these is 400 NAV_TYPE_MISMATCH. Your own folders hold either kind. ACCESS (CPO-131): Requires Admin or Developer access to CHANGE the structure, the same access as editing the schema; anyone who can read content can call get_content_structure. A 403 SCHEMA_ACCESS_REQUIRED means the person behind this connection is not an Admin or Developer: stop and tell the user, do not retry. ROOT PINS (CPO-132): folderId \'root\' pins a page or collection at the top level; null returns it to its home (Static pages / Collections). Pins sit above the folders, in their own order, and may be pages or collections. In a document a pin is folderId "home:root", a virtual id with no folder record (a folder record with that id is 400 NAV_SYSTEM_FOLDER). KIND CHECK: an id is either a page or a collection, never both, and a custom folder holds either \u2014 so move_to_folder and set_icon VERIFY that the id really is the `kind` you named on this branch, and refuse a mismatch with 400 NAV_KIND_MISMATCH naming the kind to use; call it again with that kind, which also clears the wrong-kind entry. An id that resolves to nothing is allowed (it may exist on another branch) and the result says so. set_content_structure never refuses: it returns `warnings` and `kindMismatches`. get_content_structure marks such items `kindMismatch: true` and lists them in `summary.kindMismatches`. PAGE-BOUND MODELS (CPO-135): a page with fields has a content model bound to it. That model is NOT a collection \u2014 get_content_structure never lists it among collections or in the tree, and move_to_folder / set_icon / set_content_structure refuse it with 400 NAV_PAGE_BOUND_MODEL naming the owning page (\'This model belongs to the page "\u2026"; organise the page.\'). Organise the PAGE instead, by its page id. If a stored document still references one it appears in `summary.hiddenItems` with `boundToPageId`, and the next single write drops it.';
+function structureResult(d) {
+  const message = d?.message;
+  return ok(typeof message === "string" ? message : "Updated the Content structure.", d);
+}
 function ok(summary, data) {
   return {
     content: [
@@ -2927,6 +3052,107 @@ function buildToolDefs(deps) {
         z.object({ formId: z.string().min(1), submissionId: z.string().min(1) }).shape,
         async (c, a) => ok("Deleted submission.", await data(c, "DELETE", `/management/forms/${s(a.formId)}/submissions/${s(a.submissionId)}`))
       ),
+      // ── Content structure: the Content sidebar's folders and icons (CPO-127 f) ──
+      def(
+        "get_content_structure",
+        "Get the Content sidebar structure",
+        `Read the Content sidebar's structure for the connected project: its folders, which pages and collections sit in each, and their icons. Returns { doc, version, summary }: \`doc\` is the raw document ({ schema: 1, folders: [{ id, parentId, name, icon, sort }], items: [{ kind: 'page'|'collection', id, folderId, sort, icon }] }), \`version\` is what set_content_structure needs, and \`summary\` is the resolved tree with page and collection TITLES (\`outline\` is a readable version), ids that no longer resolve (\`missing\`), and the pages and collections not in any folder yet. Call it before changing the structure, and read the resource ${STRUCTURE_PLAYBOOK_URI} (the structure standard) before you organise anything. ${STRUCTURE_NOTE}`,
+        z.object({}).shape,
+        async (c) => {
+          const d = await data(c, "GET", `/management/content-structure`);
+          return ok(d?.summary?.outline ? `Content structure:
+${d.summary.outline}` : "Content structure.", d);
+        }
+      ),
+      def(
+        "suggest_content_structure",
+        "Propose the standard Content structure",
+        `READ-ONLY: propose the standard Content sidebar structure for the connected project (${STRUCTURE_PLAYBOOK_URI}) and write NOTHING. Runs the platform's own implementation of the standard over the project's pages, collections, their references and the routes its build serves: the home page and each collection's list page pinned at the top, one folder per content family (Blog posts, Products with its taxonomies, grouped by the reference graph), shared taxonomies in Other content, standalone and code-only pages in Static pages, at most 2 levels deep. Page-bound models are never filed. Returns { doc, version, hasDocument, outline, rationale }. To apply it: show the user the outline, then call set_content_structure with this doc and this version (the If-Match; a 412 means someone changed the sidebar, so suggest again). When hasDocument is true the project already has a structure somebody made: never replace it without the user's yes; file only what is new with move_to_folder instead.`,
+        z.object({
+          maxDepth: z.number().int().min(1).max(4).optional().describe("folder nesting to propose; default 2 (the standard), 4 is the hard limit")
+        }).shape,
+        async (c, a) => {
+          const d = await data(c, "GET", `/management/content-structure/suggest${q({ maxDepth: a.maxDepth })}`);
+          return ok(d?.outline ? `Proposed Content structure (nothing was written):
+${d.outline}` : "Proposed Content structure.", d);
+        }
+      ),
+      def(
+        "set_content_structure",
+        "Replace the Content sidebar structure",
+        `Replace the whole Content sidebar document in one write. Follow the structure standard (read ${STRUCTURE_PLAYBOOK_URI} first; suggest_content_structure returns a ready doc). Prefer the single-action tools (create_folder, rename_folder, move_to_folder, set_icon, delete_folder) for small changes; use this to lay out a full structure at once. Send the complete \`doc\` and the \`version\` get_content_structure returned (0 when the project has none yet). Validated exactly like the dashboard: unique folder ids, every parentId/folderId must be a folder in the doc, no cycles, depth at most 4, names 1-80 chars, lucide icon names. A 412 VERSION_CONFLICT means someone changed it since you read it: call get_content_structure again and re-apply your change. Returns the new version and a diff (folders added, removed, renamed or moved; items moved; icons changed). ${STRUCTURE_NOTE}`,
+        z.object({
+          doc: z.object({
+            schema: z.literal(1),
+            folders: z.array(z.object({
+              id: z.string().min(1).describe("your own stable id, up to 64 chars"),
+              parentId: z.string().nullable().describe("parent folder id; null = top level"),
+              name: z.string(),
+              icon: z.string().nullable().describe("lucide icon name or null"),
+              sort: z.number()
+            })),
+            items: z.array(z.object({
+              kind: z.enum(["page", "collection"]),
+              id: z.string().min(1).describe("page id or collection (content model) id"),
+              folderId: z.string().nullable().describe('folder id; "home:root" = pinned at the top level; null = its home (Static pages for a page, the Collections list for a collection)'),
+              sort: z.number(),
+              icon: z.string().nullable()
+            }))
+          }).describe("the complete document"),
+          version: z.number().int().min(0).describe("the version get_content_structure returned")
+        }).shape,
+        async (c, a) => structureResult(await data(c, "PUT", `/management/content-structure`, { doc: a.doc, version: a.version }))
+      ),
+      def(
+        "create_folder",
+        "Create a Content sidebar folder",
+        `Create a folder in the Content sidebar, at the top level or inside \`parentId\`, placed after what is already there. Returns the new \`folderId\`. Reads, applies and writes with the version check, retrying once on a conflict. ${STRUCTURE_NOTE}`,
+        z.object({
+          name: z.string().min(1).describe("the folder's label, 1-80 chars"),
+          parentId: z.string().min(1).optional().describe("optional parent folder id (from get_content_structure); omit it, or send 'root', for the top level"),
+          icon: z.string().min(1).optional().describe("optional lucide icon name, e.g. 'folder'")
+        }).shape,
+        async (c, a) => structureResult(await data(c, "POST", `/management/content-structure/folders`, { name: a.name, parentId: a.parentId, icon: a.icon }))
+      ),
+      def(
+        "rename_folder",
+        "Rename a Content sidebar folder",
+        `Rename a Content sidebar folder. ${STRUCTURE_NOTE}`,
+        z.object({
+          folderId: z.string().min(1).describe("folder id (from get_content_structure)"),
+          name: z.string().min(1).describe("the new label, 1-80 chars")
+        }).shape,
+        async (c, a) => structureResult(await data(c, "PATCH", `/management/content-structure/folders/${encodeURIComponent(s(a.folderId))}`, { name: a.name }))
+      ),
+      def(
+        "move_to_folder",
+        "Move into a Content sidebar folder",
+        `Move a page, a collection or a folder into a folder. folderId null moves it back to its home: Static pages for a page, the Collections list for a collection, the top level for a folder. It lands after what is already there. Moving a folder takes its contents with it and is refused if the result would nest deeper than 4 levels or put a folder inside itself. ${STRUCTURE_NOTE}`,
+        z.object({
+          kind: z.enum(["page", "collection", "folder"]),
+          id: z.string().min(1).describe("the page id, collection (content model) id, or folder id"),
+          folderId: z.string().min(1).nullable().describe("target folder id; 'root' pins a page or collection at the top level (for a folder, 'root' is the top level); null moves it back to its home (Static pages, the Collections list, or the top level for a folder)")
+        }).shape,
+        async (c, a) => structureResult(await data(c, "POST", `/management/content-structure/move`, { kind: a.kind, id: a.id, folderId: a.folderId }))
+      ),
+      def(
+        "set_icon",
+        "Set a Content sidebar icon",
+        `Set or clear the sidebar icon of a page, a collection or a folder. ${STRUCTURE_NOTE}`,
+        z.object({
+          kind: z.enum(["page", "collection", "folder"]),
+          id: z.string().min(1).describe("the page id, collection (content model) id, or folder id"),
+          icon: z.string().min(1).nullable().describe("lucide icon name, e.g. 'file-text'; null clears it")
+        }).shape,
+        async (c, a) => structureResult(await data(c, "POST", `/management/content-structure/icon`, { kind: a.kind, id: a.id, icon: a.icon }))
+      ),
+      def(
+        "delete_folder",
+        "Delete a folder (its contents move up; nothing is deleted)",
+        `Delete a folder (its contents move up; nothing is deleted). NOTHING ELSE IS DELETED: its pages, collections and sub-folders move up to the folder's parent, in the same order. ${STRUCTURE_NOTE}`,
+        z.object({ folderId: z.string().min(1).describe("folder id (from get_content_structure)") }).shape,
+        async (c, a) => structureResult(await data(c, "DELETE", `/management/content-structure/folders/${encodeURIComponent(s(a.folderId))}`))
+      ),
       def(
         "list_redirects",
         "List redirects",
@@ -3169,14 +3395,14 @@ function buildToolDefs(deps) {
       def(
         "update_page",
         "Edit a page",
-        "Edit a page: title, slug, SEO metaTitle/metaDescription, publish status (draft|published), and `blockJson` (its block composition \u2014 passing it REPLACES the whole array, so read get_page first). It does NOT change the field SCHEMA \u2014 use add_page_field / set_page_content for that. Renaming the slug keeps content intact. Publishing copies the draft blocks live in the same call. " + SECTION_DOCTRINE,
-        z.object({ pageId: z.string().min(1), title: z.string().optional(), slug: z.string().optional(), blockJson: z.array(blockObject).optional().describe("REPLACES the page's block composition"), metaTitle: z.string().optional(), metaDescription: z.string().optional(), status: z.enum(["draft", "published"]).optional() }).shape,
+        "Edit a page: title, slug, SEO metaTitle/metaDescription, structured data (`schemaType`, `schema`), publish status (draft|published), and `blockJson` (its block composition \u2014 passing it REPLACES the whole array, so read get_page first). It does NOT change the field SCHEMA \u2014 use add_page_field / set_page_content for that. Renaming the slug keeps content intact. Publishing copies the draft blocks live in the same call. STRUCTURED DATA is native SEO, never a field: leave it out and the page gets Automatic JSON-LD from its content (WebSite on the home page, Blog/CollectionPage on a collection's list page, WebPage otherwise); `schemaType` picks an explicit schema.org type whose properties are filled from the content; `schema` is pasted JSON-LD and wins over both (null clears it). " + SECTION_DOCTRINE,
+        z.object({ pageId: z.string().min(1), title: z.string().optional(), slug: z.string().optional(), blockJson: z.array(blockObject).optional().describe("REPLACES the page's block composition"), metaTitle: z.string().optional(), metaDescription: z.string().optional(), schemaType: z.enum(["auto", "WebPage", "AboutPage", "ContactPage", "CollectionPage", "Blog", "BlogPosting", "Article", "Product", "FAQPage", "Event", "Organization", "LocalBusiness"]).optional().describe("structured data type; 'auto' (the default) derives it from the content"), schema: z.union([z.record(z.string(), z.unknown()), z.array(z.record(z.string(), z.unknown()))]).nullable().optional().describe("custom JSON-LD; wins over schemaType; null clears it"), status: z.enum(["draft", "published"]).optional() }).shape,
         async (c, a) => {
           const res = await c.fetchJSON(
             c.url(`/management/pages/${s(a.pageId)}/meta`),
             {
               method: "PATCH",
-              body: JSON.stringify({ title: a.title, slug: a.slug, blockJson: a.blockJson, metaTitle: a.metaTitle, metaDescription: a.metaDescription, status: a.status })
+              body: JSON.stringify({ title: a.title, slug: a.slug, blockJson: a.blockJson, metaTitle: a.metaTitle, metaDescription: a.metaDescription, schemaType: a.schemaType, schema: a.schema, status: a.status })
             }
           );
           const note = res.redirectNote;
@@ -3235,7 +3461,7 @@ function buildToolDefs(deps) {
       def(
         "get_next_steps",
         "Get what to do next",
-        "What is still unfinished in the connected project, as the platform sees it \u2014 pages you created without a meta description, drafts never published, collections with no entries, forms nobody is notified about, writes waiting for human approval. Each item cites the count it reacted to. Call it AFTER a batch of edits to catch what you left behind, and before telling the user you are done.",
+        `What is still unfinished in the connected project, as the platform sees it \u2014 pages you created without a meta description, drafts never published, collections with no entries, forms nobody is notified about, writes waiting for human approval. Each item cites the count it reacted to. Call it AFTER a batch of edits to catch what you left behind, and before telling the user you are done. When it lists \`organise-content\`, the project's pages and collections are in no folder: read ${STRUCTURE_PLAYBOOK_URI}, call suggest_content_structure and apply it with set_content_structure once the user agrees.`,
         z.object({}).shape,
         async (c) => ok("Next steps.", await data(c, "GET", `/management/insights/next-steps`))
       ),
@@ -5797,9 +6023,23 @@ function buildServer(deps) {
       // 🔴 The plain-language ask, routed — the stdio twin of the hosted connector's line
       // (src/routes/mcp/index.ts MCP_INSTRUCTIONS). "Make my site editable" has one recipe and
       // one definition of done; without this an agent converts the page it landed on and stops.
-      instructions: "When the user asks to make a site or all of its pages editable, to convert it, or to bind its fields: this is playbook \xA713. Read `bettercms://playbook/schema` \xA713, call get_binding_report and get_conversion_brief { complete: true }, convert EVERY route the brief lists, and finish only when get_binding_report shows coverage.pending empty on every route \u2014 not when the first page works. On a workspace-wide connection pass projectId on every call; never ask the user to re-scope the connection. When the user asks to componentize the whole site, to turn every section into a component, or to build a component library from the site: this is playbook \xA712. Read `bettercms://playbook/schema` \xA712, start with get_site_composition, and use the batch tools \u2014 create_components, compose_pages, update_layout with `commands`, publish_components \u2014 rather than one call per component. Finish with get_site_composition and tell the user what the platform does not model (cookie banners, modals, breadcrumbs, pagination) and which components still need the owner's approval in the dashboard before they can be published. BetterCMS never executes a customer's Section renderer or app code. An ordinary MCP connection is not a push runner: explicitly poll list_section_validation_requests, claim one request at an exact git commit, run implementation and responsive checks inside the user's own repository and real app shell, then submit manifest + validation with that requestId and complete it\u2014or truthfully fail it when implementation/evidence is missing. Never invent a manifest, a passing validation, or visual evidence; these tools cannot grant the separate human Visual Approval required for publication."
+      instructions: "When the user asks to make a site or all of its pages editable, to convert it, or to bind its fields: this is playbook \xA713. Read `bettercms://playbook/schema` \xA713, call get_binding_report and get_conversion_brief { complete: true }, convert EVERY route the brief lists, and finish only when get_binding_report shows coverage.pending empty on every route \u2014 not when the first page works. On a workspace-wide connection pass projectId on every call; never ask the user to re-scope the connection. When the user asks to componentize the whole site, to turn every section into a component, or to build a component library from the site: this is playbook \xA712. Read `bettercms://playbook/schema` \xA712, start with get_site_composition, and use the batch tools \u2014 create_components, compose_pages, update_layout with `commands`, publish_components \u2014 rather than one call per component. Finish with get_site_composition and tell the user what the platform does not model (cookie banners, modals, breadcrumbs, pagination) and which components still need the owner's approval in the dashboard before they can be published. BetterCMS never executes a customer's Section renderer or app code. An ordinary MCP connection is not a push runner: explicitly poll list_section_validation_requests, claim one request at an exact git commit, run implementation and responsive checks inside the user's own repository and real app shell, then submit manifest + validation with that requestId and complete it\u2014or truthfully fail it when implementation/evidence is missing. Never invent a manifest, a passing validation, or visual evidence; these tools cannot grant the separate human Visual Approval required for publication. " + // The default after authoring (the structure standard): organise what you made. Same
+      // sentence as the hosted connector's MCP_INSTRUCTIONS.
+      STRUCTURE_DEFAULT_INSTRUCTION
     }
   );
+  server.registerResource(
+    "structure-playbook",
+    STRUCTURE_PLAYBOOK_URI,
+    {
+      title: "BetterCMS Content structure playbook",
+      description: "How to organise a project's Content sidebar: one place per document, the home page and list pages pinned, one folder per content family grouped by the reference graph, shared taxonomies in Other content, Static pages for the rest, at most 2 levels. With a worked set_content_structure payload.",
+      mimeType: "text/markdown"
+    },
+    () => ({
+      contents: [{ uri: STRUCTURE_PLAYBOOK_URI, mimeType: "text/markdown", text: STRUCTURE_PLAYBOOK }]
+    })
+  );
   server.registerResource(
     "schema-playbook",
     PLAYBOOK_URI,