@bettercms-ai/mcp 0.20.1 → 0.22.0

package/SKILL.md

@@ -31,6 +31,65 @@ Within a page's own schema, destructure into a tree: plain fields, **group** (on
 object), **repeater** (a repeatable array). Never a 1-item repeater, never a repeater of a
 single text (that is `array`).
 
+### A page is a list of SECTIONS. Never a list of loose blocks.
+
+The top level of a page's `blockJson` holds only `component` blocks or `section` blocks —
+never a bare `heading`/`text`/`image`/`button`/`spacer`.
+
+**Why it matters, concretely:** the visual editor derives one section per TOP-LEVEL block. A
+hero authored as four loose blocks (headline, lede, two CTAs) becomes four separate sections,
+each with its own move / duplicate / delete controls and its own "Add section here" gap — and
+because each top-level block gets its own block box, the two call-to-action buttons stop being
+inline siblings and **stack onto separate lines**. That is not a styling bug to chase in CSS;
+it is the page telling you it was authored flat.
+
+```jsonc
+// ✅ one section, four children — one set of controls, CTAs side by side
+{ "type": "section", "id": "hero",
+  "style": { "bg": "surface", "paddingTop": 96, "paddingBottom": 96, "contentWidth": "default" },
+  "props": { "children": [
+    { "type": "heading", "id": "hero-title", "props": { "text": "Strategic Planning.", "level": 1 } },
+    { "type": "text",    "id": "hero-lede",  "props": { "html": "<p>One place to plan, track and ship.</p>" } },
+    { "type": "button",  "id": "hero-cta",   "props": { "text": "Start a project", "href": "/contact" } },
+    { "type": "button",  "id": "hero-cta2",  "props": { "text": "See our work", "href": "/work", "variant": "secondary" } }
+  ] } }
+```
+
+**Two CTAs are two sibling `button` blocks.** Not a `columns` block — `columns` renders
+`grid-template-columns: repeat(N, 1fr)`, so each CTA would stretch to half the container.
+Buttons are inline-level and flow side by side on their own. This is what the shipped
+`builtin:hero-centered` section does.
+
+### `section` block or `component`? Decide by REUSE.
+
+| | use it when | the catch |
+|---|---|---|
+| **`component`** (+ `sectionType`) | the band appears on more than one page, or needs layout variants — a Hero that is "Centered" on Home and "Two-column" on About | its children render **without field bindings**, so their text is **not click-to-edit on the canvas**. It is edited through the component's declared `props` in the section dock, where an unset prop shows empty and inherits the definition's default. Authors who want the current copy visible in the dock should set the prop explicitly rather than relying on the inherited default. |
+| **`section` block** | a genuinely one-off band on a single page | no family name and no variant switcher, and the editor's "Add a section" picker cannot insert one — only components |
+
+`component` is the shape the product's reuse machinery is built around: variants, the section
+picker and the family name all key off `componentId`. So reach for it whenever a band actually
+recurs — and when you do, **declare a prop for every string, link and image a marketer will
+ever touch**. A component with un-propped editable copy is the defect, not the component.
+
+### Don't hand-write a hero. Start from a built-in section.
+
+There are built-in section components — `hero-centered`, `hero-split`, `feature-grid-three`,
+`feature-grid-two`, `faq-list`, `stats-row`, `logo-cloud-row`, `testimonial-quote`,
+`case-study-story`, `cta-banner`, `cta-split`, `pricing-three`, `contact-simple` — available to
+every project (`list_components` returns them; they have no `projectId`). Every one is already
+rooted in a `section` block with its editable leaves declared as props, and `Hero` ships two
+variants, so the shapes above are worked examples you can read.
+
+Two sanctioned recipes, and which one you want follows the reuse rule above:
+
+1. **Inline it** — copy the builtin's `section` blockJson onto the page as a `section` block and
+   substitute your values. Standard path for a one-off band; children stay click-to-edit.
+2. **Reference it** — place `{ type: "component", props: { componentId, overrides } }`. Use this
+   when the band recurs across pages or needs the variant switcher.
+
+Authoring a hero's JSON from scratch is the slow way to reinvent recipe 1 with more mistakes.
+
 The full decision tree, section anatomy, variant rules and build order live in the
 `propose_schema` prompt and in the `bettercms://playbook/schema` resource.
 
@@ -52,10 +111,18 @@ Tools: `list_forms`, `get_form`, `create_form`, `update_form`.
 ## Components (reusable Webflow-style symbols)
 Tools: `list_components`, `get_component`, `create_component`, `update_component`.
 
-1. Design the `blockJson` tree — an array of blocks `{ type, id, props }`. Types:
-   `heading {text, level}`, `text {text}`, `image {src, alt}`, `button {text, href}`,
-   `spacer {height}`, `video {url}`, and `columns {columns: block[][], gap}` which nests
-   child blocks. Every block needs a stable unique `id`.
+1. Design the `blockJson` tree — an array of blocks `{ type, id, props }`. The full set:
+   `heading {text, level}`, `text {html}`, `richtext {html}`, `image {src, alt}`,
+   `button {text, href, variant?}`, `spacer {height}`, `video {url}`,
+   `columns {columns: block[][], gap}`, `section {children: block[]}`,
+   `slider {slides}`, `tabs {tabs}`, `navbar {links, logo?, cta?}`, `footer {columns, copyright?}`,
+   `form {formId}`, `component {componentId, overrides?}`, `collection {…}`.
+   `section`, `columns`, `slider` and `tabs` nest child blocks. Every block needs a stable
+   unique `id`.
+
+   ⚠️ `text` and `richtext` carry **`html`**, never `text`. `props.html` is required with no
+   default, so `{ text: "…" }` is a **400 on every save** — not a silent strip. This file said
+   `text {text}` until 2026-08-20; if you learned it from an older copy, unlearn it.
 2. Optional `props` — overridable fields `{ key, label, target: { blockId, path }, type,
    defaultValue? }` (type: `text|richtext|image|url|boolean`) so each instance can be
    customized.

package/dist/index.js

@@ -314,7 +314,9 @@ import { BetterCMS } from "@bettercms-ai/sdk";
 
 // src/tools.ts
 import { z } from "zod";
-import { BetterCMSError } from "@bettercms-ai/sdk";
+
+// ../types/src/component.ts
+var SECTION_DOCTRINE = "STRUCTURE (separate from schema): a page is composed of SECTIONS. NEVER build a page out of loose top-level heading/text/image/button/spacer blocks \u2014 they cannot be moved, duplicated or swapped as a unit, the visual editor cannot outline or name them, and every one of them becomes its own section in the editor. A hero of a headline, a lede and two CTAs is ONE section, not four. TWO SHAPES, and the choice is about REUSE. (1) A band that appears on more than one page, or that needs layout variants, is a COMPONENT with a `sectionType` \u2014 see create_component. Components sharing a `sectionType` are that section's VARIANTS (one Hero: 'Centered' for the home page and 'Two-column' for about, same prop keys so a swap keeps the content). This is also the only shape the editor's 'Add a section' picker can insert, and the only one that gets a family name and a variant switcher. (2) A genuinely one-off band on a single page is a `section` BLOCK whose `props.children` hold its blocks. THE TRADEOFF, stated in the present tense because it is real today: a component's children render WITHOUT field bindings, so their text is NOT click-to-edit on the canvas \u2014 it is edited through the component's declared `props` in the section dock. A `section` block's children stay click-to-edit. So when you choose a component, DECLARE A PROP for every string, link and image a marketer will ever touch; a component with un-propped editable copy is the defect, not the component. In the dock an unset prop shows EMPTY and inherits the definition's default, so set props explicitly when you want the current copy visible there. Do not hand-write a band's JSON: start from a built-in section component (list_components returns them with no projectId \u2014 hero-centered, hero-split, feature-grid-three, cta-banner and nine more), each already rooted in a `section` block with its editable leaves declared as props. INLINE its blockJson as a `section` block for a one-off band; REFERENCE it as a `component` when the band recurs or needs variants. Two consecutive call-to-action buttons are two sibling `button` blocks inside the same section \u2014 never a `columns` block, which is a `repeat(N,1fr)` grid and would stretch each CTA to half the container. Buttons are inline-level and flow side by side on their own.";
 
 // ../types/src/layout-lucide-icons.ts
 var LAYOUT_SECTION_ICONS = Object.freeze([
@@ -2279,6 +2281,7 @@ var LAYOUT_SECTION_ICONS = Object.freeze([
 var LAYOUT_SECTION_ICON_SET = new Set(LAYOUT_SECTION_ICONS);
 
 // src/tools.ts
+import { BetterCMSError } from "@bettercms-ai/sdk";
 var FRAMEWORK_CHOICES = ["astro", "next", "react-ts", "other"];
 var FRAMEWORK_LABELS = {
   astro: "Astro \u2014 recommended default, static by default and fastest to publish",
@@ -2319,6 +2322,46 @@ async function askFramework(deps) {
   }
   return { prompt: FRAMEWORK_PROMPT };
 }
+var AUTHORING_CHOICES = ["components", "fields"];
+var AUTHORING_LABELS = {
+  components: "Components \u2014 reusable section components placed as blocks; editors add, reorder and swap sections without touching a schema. Best for marketing and landing sites",
+  fields: "Fields \u2014 a typed field schema per page. Best for blogs, catalogues and directories, where many rows share one shape"
+};
+var AUTHORING_PROMPT = [
+  "Ask the user which authoring architecture this site should use, then call set_authoring_preference again with their answer as `preference`:",
+  ...AUTHORING_CHOICES.map((c, i) => `  ${i + 1}. ${c} \u2014 ${AUTHORING_LABELS[c]}`),
+  "",
+  "Answering 'components' does not convert anything \u2014 there is no field-to-block converter. It means you author the sections yourself: create_component, then publish_component (an unpublished component renders as NOTHING on the live site), then set_page_content placing `component` blocks. Once a page has blocks, list_extraction_candidates and extract_component fold the repeats.",
+  "",
+  "Do not choose on their behalf. This is asked once per project."
+].join("\n");
+async function askAuthoring(deps) {
+  if (!deps.elicit) return { prompt: AUTHORING_PROMPT };
+  try {
+    const res = await deps.elicit({
+      message: "Which authoring architecture should this site use?",
+      requestedSchema: {
+        type: "object",
+        properties: {
+          preference: {
+            type: "string",
+            title: "Authoring architecture",
+            description: "How this site's pages are composed. Asked once per project.",
+            enum: [...AUTHORING_CHOICES],
+            enumNames: AUTHORING_CHOICES.map((c) => AUTHORING_LABELS[c])
+          }
+        },
+        required: ["preference"]
+      }
+    });
+    const picked = res.action === "accept" ? res.content?.preference : void 0;
+    if (typeof picked === "string" && AUTHORING_CHOICES.includes(picked)) {
+      return { preference: picked };
+    }
+  } catch {
+  }
+  return { prompt: AUTHORING_PROMPT };
+}
 var fieldType = z.enum([
   "text",
   "richtext",
@@ -2619,7 +2662,14 @@ function buildToolDefs(deps) {
     options: z.array(z.string()).optional().describe("choices when type is 'select', 'radio' or 'checkboxes'"),
     hidden: z.boolean().optional().describe("not rendered; pairs with defaultValue to capture context"),
     defaultValue: z.string().optional(),
-    showIf: z.object({ field: z.string(), equals: z.string() }).optional().describe("show this field only when another field equals a value")
+    showIf: z.object({ field: z.string(), equals: z.string() }).optional().describe("show this field only when another field equals a value"),
+    validation: z.object({
+      emailPolicy: z.enum(["any", "business"]).optional().describe("'email' fields only"),
+      min: z.number().optional().describe("'number' fields only \u2014 inclusive floor"),
+      max: z.number().optional().describe("'number' fields only \u2014 inclusive ceiling"),
+      phoneFormat: z.enum(["any", "e164"]).optional().describe("'phone' fields only"),
+      pattern: z.string().optional().describe("'text' / 'textarea' / 'url' fields only \u2014 a regex")
+    }).optional().describe("per-field rules the API enforces on submit; each key is only valid on the field types listed")
   });
   const formSettingsShape = {
     description: z.string().optional(),
@@ -2642,11 +2692,26 @@ function buildToolDefs(deps) {
     key: z.string().min(1),
     label: z.string().min(1),
     target: z.object({ blockId: z.string().min(1), path: z.string().min(1) }),
-    type: z.enum(["text", "richtext", "image", "url", "boolean", "slot"]),
+    // MUST stay at parity with componentPropDefSchema on the server. `update_component`
+    // REPLACES the whole `props` array, so a type this enum omits cannot be echoed back: an
+    // agent that reads a component and writes it back DESTROYS every prop of that type.
+    type: z.enum(["text", "richtext", "image", "url", "boolean", "number", "select", "group", "table", "slot"]),
     // 'slot' holds ONE nested component instance; config.componentIds restricts what may
     // fill it. Absent here until now, so a slot allowlist was unreachable from stdio even
     // once the enum allowed the type.
-    config: z.object({ componentIds: z.array(z.string()).optional() }).optional(),
+    config: z.object({
+      componentIds: z.array(z.string()).optional(),
+      // 'slot' allowlist
+      options: z.array(z.string()).optional(),
+      // 'select' — required, choices
+      // 'group'/'table' sub-shape. Typed loosely here (the server validates the full
+      // recursive shape) so a 3-level tree does not need a 3-level Zod mirror in the client.
+      fields: z.array(z.record(z.string(), z.unknown())).optional(),
+      min: z.number().optional(),
+      // 'number'
+      max: z.number().optional(),
+      step: z.number().optional()
+    }).passthrough().optional(),
     defaultValue: z.unknown().optional()
   });
   const getLayoutInput = z.object({
@@ -2718,7 +2783,9 @@ function buildToolDefs(deps) {
     componentId: z.string().min(1).describe("component id (from list_components)"),
     name: z.string().optional(),
     category: componentCategory.optional(),
-    sectionType: sectionType.nullable().optional().describe("null demotes it to an ordinary component"),
+    sectionType: sectionType.nullable().optional().describe(
+      "null demotes it to an ordinary component \u2014 it disappears from the 'Add a section' picker, and instances already placed keep rendering but lose their section chrome and variant switcher"
+    ),
     allowedOn: allowedOn.optional().describe("REPLACES the placement allowlist"),
     description: z.string().optional(),
     blockJson: z.array(blockObject).optional().describe("REPLACES the block tree"),
@@ -2977,6 +3044,25 @@ function buildToolDefs(deps) {
           return ok("Created project.", await data(c, "POST", `/management/projects`, { ...a, framework }));
         }
       ),
+      def(
+        "set_authoring_preference",
+        "Set the site's authoring architecture",
+        "Record which authoring architecture this site uses \u2014 'components' (reusable section components placed as blocks; editors add, reorder and swap sections without touching a schema \u2014 best for marketing and landing sites) or 'fields' (a typed field schema per page \u2014 best for blogs, catalogues and directories). ASK THE USER; do not pick for them. Called without `preference`, this tool asks them directly (or hands you the question to ask). deploy_project, deploy_from_upload and promote_project all refuse with 409 AUTHORING_DECISION_REQUIRED until it is set, and that refusal carries this project's real page counts to show the user. Answering 'components' does NOT convert anything \u2014 there is no field-to-block converter; it means you author the sections yourself: create_component, then publish_component (an unpublished component renders as NOTHING on the live site), then set_page_content placing `component` blocks. Asked once per project; re-callable if the user changes their mind.",
+        // Optional in the schema for exactly the reason `framework` is above: a required arg is
+        // rejected by the SDK before the handler runs, which would kill the elicitation below
+        // and leave the model guessing. Optional here, answered by a human there. The backend
+        // gate refuses the deploy regardless, so nothing ships on a guess.
+        z.object({ preference: z.enum(AUTHORING_CHOICES).optional().describe("REQUIRED in effect \u2014 the architecture the USER chose. Ask them; never default it.") }).shape,
+        async (c, a) => {
+          let preference = a.preference;
+          if (preference === void 0) {
+            const asked = await askAuthoring(deps);
+            if ("prompt" in asked) return fail(asked.prompt);
+            preference = asked.preference;
+          }
+          return ok("Recorded the authoring architecture.", await data(c, "PATCH", `/management/projects/current/authoring-preference`, { preference }));
+        }
+      ),
       def(
         "clone_project",
         "Clone a project",
@@ -3031,7 +3117,7 @@ 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.",
+        "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,
         async (c, a) => ok("Updated page.", await data(c, "PATCH", `/management/pages/${s(a.pageId)}/meta`, { title: a.title, slug: a.slug, blockJson: a.blockJson, metaTitle: a.metaTitle, metaDescription: a.metaDescription, status: a.status }))
       ),
@@ -3210,7 +3296,7 @@ function buildToolDefs(deps) {
       name: "create_page",
       config: {
         title: "Create a page",
-        description: "Create a page with its own typed schema. Supports pageType 'singleton' (exactly one entry \u2014 Home, About, Contact) and 'dynamic' (many entries sharing the schema \u2014 Blog posts, Products). Project-scoped from the key. Additive \u2014 does not delete or overwrite existing pages. FIRST read the page's real markup and DECOMPOSE it into a destructured tree: each visual section becomes a nested field \u2014 a fixed grouped block \u2192 type 'group', a repeating list of items (cards, testimonials, features, FAQs) \u2192 type 'repeater' \u2014 each carrying its own child `fields`. Do NOT flatten sections into many flat top-level fields. Build the full nested tree, then call this once.",
+        description: "Create a page with its own typed schema. Supports pageType 'singleton' (exactly one entry \u2014 Home, About, Contact) and 'dynamic' (many entries sharing the schema \u2014 Blog posts, Products). Project-scoped from the key. Additive \u2014 does not delete or overwrite existing pages. FIRST read the page's real markup and DECOMPOSE it into a destructured tree: each visual section becomes a nested field \u2014 a fixed grouped block \u2192 type 'group', a repeating list of items (cards, testimonials, features, FAQs) \u2192 type 'repeater' \u2014 each carrying its own child `fields`. Do NOT flatten sections into many flat top-level fields. Build the full nested tree, then call this once. That tree is the page's SCHEMA \u2014 what it holds. " + SECTION_DOCTRINE,
         inputSchema: createPageInput.shape
       },
       handler: guard(
@@ -3567,7 +3653,7 @@ function buildToolDefs(deps) {
       name: "create_component",
       config: {
         title: "Create a reusable component",
-        description: "Create a reusable component from a blockJson tree. CONFIRM the structure with the user first. blockJson is an array of blocks (heading/text/image/button/spacer/video/columns); a 'columns' block nests child blocks in props.columns. `props` declares overridable fields. Returns the new id \u2014 render with `<BcmsBlocks>`. Always lands as a DRAFT: it is not on the live site until someone publishes it from the dashboard.",
+        description: "Create a reusable component from a blockJson tree. THIS IS ALSO HOW A PAGE GETS ITS SECTIONS: set `sectionType` (e.g. 'Hero') and the component becomes a placeable section, selectable in the editor's 'Add a section' picker. Components sharing a `sectionType` are its layout VARIANTS \u2014 one Hero with a 'Centered' and a 'Two-column' variant, same prop keys, so a swap keeps the content. CONFIRM the structure with the user first. blockJson is an array of blocks \u2014 the same set create_page accepts (heading, text/richtext, image, button, spacer, video, columns, section, slider, tabs, navbar, footer, form, component, collection), NOT a narrower one; `section` nests child blocks in props.children and `columns` in props.columns. `props` declares overridable fields. Returns the new id \u2014 render with `<BcmsBlocks>`. Always lands as a DRAFT: it is not on the live site until someone publishes it from the dashboard. " + SECTION_DOCTRINE,
         inputSchema: createComponentInput.shape
       },
       handler: guard(
@@ -3750,8 +3836,13 @@ Then declare what an editor may change, via \`props\`:
       { key: "ctaHref",  label: "CTA link", target: { blockId: "cta", path: "props.href" }, type: "url" }
     ]
 
-Declare props only for what should really be editable. Every prop is a decision an editor
-has to make.
+\u{1F534} **On a components-first page, \`props\` is the ONLY editing surface.** Click-to-edit binds
+\`heading\`/\`text\`/\`button\`/\`image\` blocks; it does **not** bind a \`component\` block, because
+a component's blocks belong to the shared definition, not to the instance. So a page built
+from \`component\` blocks renders correctly and emits ZERO fields on the canvas \u2014 editing goes
+through the declared props allowlist to per-instance overrides. **A component with no props
+is a section nobody can change.** Declare a prop for every string, link and image a marketer
+would ever reasonably want to touch; leave out only structure and styling.
 
 ## 4. Variants
 
@@ -3814,9 +3905,98 @@ nothing, on a page that returns 200. If a section is missing from the live site,
 
 **A workspace-level component (\`projectId: null\`) never reaches a live site.** It resolves
 in preview and is blank in production. Always pass the project's id.
+
+## 9. Check which project you are bound to, BEFORE you build
+
+\`create_project\` succeeds on a project-scoped connection and hands back a real new project
+\u2014 but every write that follows still lands in the project your grant is bound to.
+\`projectId\` is forwarded as a header for a workspace-scoped grant; a **project-scoped grant
+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.
+
+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
+written to the wrong project can only be demoted (\`sectionType: null\`) and left unpublished.
+
+## 10. You imported a site, or you are about to deploy one
+
+\`deploy_project\`, \`deploy_from_upload\` and \`promote_project\` all answer **409
+AUTHORING_DECISION_REQUIRED** until a human has chosen this project's architecture. This is
+asked ONCE per project, ever. It is not an error to retry or route around: read the message
+out, let the user pick, call \`set_authoring_preference\`, then deploy again.
+
+It exists because an imported site arrives **field-driven whether anyone chose that or not**
+\u2014 a crawl-based import (Webflow, a starter, a template) emits pages with a typed field schema
+and an empty block tree, because that is all a crawl can infer. Nobody decided it. On a
+marketing site it is the wrong answer, and \xA71 already says why converting later means
+rewriting content. So the platform stops once, at the last moment it is still cheap.
+
+**Answering \`components\` does not convert anything.** There is no field-to-block converter,
+and \`extract_component\` cannot stand in for one: it scans \`blockJson\`, which is empty on
+exactly the pages that would need converting. What it means is that you author the sections,
+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
+    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
+
+**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.
+
+Either way: ask, do not choose. The 409 carries this project's actual page counts \u2014 how many
+are field-driven, block-driven, and how many place a reusable component \u2014 so quote those to
+the user rather than describing the choice in the abstract.
+
+## 11. The canvas: what makes an imported site EDITABLE
+
+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 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.
+
+**Editing binds by VALUE.** The editor matches CMS field values against the text the site
+renders. Three consequences, each load-bearing:
+
+    1. Content that exists ONLY in the build can never be click-to-edit. Bring it in, per
+       route, in this order (get_next_steps reports the state until it is done):
+
+         a. create_page            one per route, slug matching the route
+         b. add_page_field         the fields its content needs (or create_component +
+                                   publish_component + component blocks, per your \xA710 answer)
+         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
+    2. A value that renders in more than one place stays uneditable on the canvas (deliberate:
+       binding it would edit all of them at once). It remains editable in the side panel.
+    3. Keep chrome semantic \u2014 \`<nav>\`, \`<footer>\`, page content inside \`<main>\`, mastheads
+       as a top-level \`<header>\`. Chrome is edited through the project Layout, not the page,
+       and semantic landmarks are how the editor keeps a nav edit from being written into page
+       content. Div-built chrome outside \`<main>\` is still excluded; div-built chrome with no
+       \`<main>\` anywhere loses that protection.
+
+**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,
+your own server) has NO canvas today: the SDK's draft mode with \`stega: true\` embeds invisible
+per-field provenance in fetched strings, which prepares the content for editing surfaces, but do
+not promise a canvas for an externally-hosted site.
 `;
 
 // src/prompts.ts
+var STRUCTURE_RULE = `### Page structure (non-negotiable)
+${SECTION_DOCTRINE}`;
 var SCHEMA_PROPOSAL_FLOW = `### Whole-project design (confirm-first) \u2192 \`create_component\` / \`create_page\` / \`create_content_model\`
 Design the WHOLE project from its brief or its code, and **confirm the shape with the user
 BEFORE creating anything**. Never silently guess.
@@ -4067,6 +4247,8 @@ the host has a stale cached MCP \u2014 tell the user to \`rm -rf ~/.npm/_npx\` a
 
 ${PAGE_FLOW}
 
+${STRUCTURE_RULE}
+
 After creating, report the page id, slug, type, field count, and the project it landed in.
 On 409 slug_taken, offer an alternative slug; on 401/403, the MCP key needs (re)authorizing.`
           }
@@ -4143,8 +4325,12 @@ On 409 slug_taken, offer an alternative slug; on 401/403, the MCP key needs (re)
             type: "text",
             text: `Build a BetterCMS site end-to-end.${request ? ` The user wants: "${request}".` : ""}
 
+${SCHEMA_PROPOSAL_FLOW}
+
 ${BUILD_SITE_FLOW}
 
+${STRUCTURE_RULE}
+
 ${SEO_FLOW}
 
 Confirm each stage with the user before writing. On 401/403, the MCP key needs (re)authorizing.`
@@ -4172,6 +4358,8 @@ Confirm each stage with the user before writing. On 401/403, the MCP key needs (
 
 ${LANDING_PAGES_FLOW}
 
+${STRUCTURE_RULE}
+
 On 401/403, the MCP key needs (re)authorizing.`
           }
         }
@@ -4197,6 +4385,44 @@ On 401/403, the MCP key needs (re)authorizing.`
 
 ${SEO_FLOW}
 
+On 401/403, the MCP key needs (re)authorizing.`
+          }
+        }
+      ]
+    })
+  );
+  server.registerPrompt(
+    "import-site",
+    {
+      title: "Make an imported site editable (guided)",
+      description: "After deploying an existing site: bring its content into the CMS so the visual editor can bind it, declare its presentation manifest, and publish everything that renders. A deploy makes a site LIVE, not EDITABLE \u2014 this flow closes that gap.",
+      argsSchema: {
+        request: z2.string().optional().describe("scope, e.g. 'all routes' or 'just the home page'")
+      }
+    },
+    ({ request }) => ({
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: `Make my imported site editable in BetterCMS.${request ? ` Scope: "${request}".` : ""}
+
+Read bettercms://playbook/schema section 11 first, then work this order:
+
+1. AUTHORING GATE \u2014 if any deploy answered 409 AUTHORING_DECISION_REQUIRED, ask ME
+   components-or-fields (do not choose), then set_authoring_preference.
+2. CONTENT INTO THE CMS, per route: create_page (slug = route) -> add_page_field (or
+   create_component + publish_component + component blocks) -> set_page_content with values
+   EXACTLY equal to the rendered text (binding matches by value; a paraphrase binds nothing)
+   -> update_page status 'published' (the canvas binds the PUBLISHED copy).
+3. PRESENTATION MANIFEST \u2014 add bcms-presentation.json to public/ (container width, type
+   scale, nav position/background, footer surface as DTCG {"$type","$value"} entries) and
+   redeploy, or structural draft previews render in a generic theme, not this site's design.
+4. VERIFY \u2014 call get_next_steps and fix what it lists (it knows about missing manifests,
+   content still only in the build, and placed-but-unpublished components), or tell me why
+   an item is being left.
+
 On 401/403, the MCP key needs (re)authorizing.`
           }
         }