@bettercms-ai/mcp 0.22.1 → 0.24.0

package/README.md

@@ -57,9 +57,9 @@ On the first tool call the server prints an authorization prompt to **stderr**
 
 ```
 ┌─ BetterCMS authorization required ─────────────────────────
-│ Visit: https://demo.bettercms.ai/activate
+│ Visit: https://bettercms.ai/activate
 │ Enter code: WDJB-MJHT
-│ Or open: https://demo.bettercms.ai/activate?code=WDJB-MJHT
+│ Or open: https://bettercms.ai/activate?code=WDJB-MJHT
 └────────────────────────────────────────────────────────────
 ```
 

package/dist/index.js

@@ -316,7 +316,7 @@ import { BetterCMS } from "@bettercms-ai/sdk";
 import { z } from "zod";
 
 // ../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.";
+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 blueprint (list_components returns locked `builtin:*` blueprints 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; for a recurring band, materialize the blueprint with create_component so it becomes project-scoped before implementation validation, Output or publication. Direct `builtin:*` component references exist only for legacy delivery compatibility. 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([
@@ -2408,10 +2408,15 @@ var fieldType = z.enum([
 var slug = z.string().regex(/^[a-z0-9-]+$/, "lowercase letters, numbers, and hyphens only");
 var fieldKey = z.string().regex(/^[a-zA-Z0-9_]+$/, "letters, numbers, and underscores only");
 var fieldShape = {
-  key: fieldKey.describe("machine field key, e.g. 'title' or 'blog_hero'"),
+  key: fieldKey.describe(
+    "machine field key. \u{1F534} UNIQUE ACROSS THE WHOLE MODEL \u2014 API IDs share ONE FLAT NAMESPACE, so a field nested inside a group must NOT reuse a key used by another field or group. Every section's heading cannot be 'title'. Prefix with the section: 'hero_title', 'pricing_title', 'faq_title'. Reusing a key is refused, and if it slips through it leaves permanent errors in the editor and breaks conditional-visibility rules, which reference fields by bare key."
+  ),
   label: z.string().min(1).describe("human label shown in the editor"),
   type: fieldType,
   required: z.boolean().optional(),
+  richText: z.boolean().optional().describe(
+    "prose formatting. DEFAULTS TO TRUE for 'text': the field is created as rich text so editors can bold, link and format it on the canvas, and the API returns rich text (render with rich() from @bettercms-ai/sdk; plain() for titles and meta). Pass false for a value that is NOT prose and must stay a bare string \u2014 a URL/href, a slug, an id, an email, a phone number, a CSS class, an icon name. A link stored as rich text will not work as an href."
+  ),
   options: z.array(z.string()).optional().describe("choices when type is 'select'"),
   config: z.record(z.string(), z.unknown()).optional().describe(
     "per-type config: reference {contentModelId}, multi-reference {contentModelId,min,max}, array {itemType: 'text'|'number'|'date'}, date {includeTime}, modular {blockSlugs: ['quote','gallery'], minItems?, maxItems?} \u2014 blockSlugs is REQUIRED, non-empty, and each slug must name an existing kind:'block' model"
@@ -2421,9 +2426,39 @@ var fieldShape = {
   )
 };
 var fieldObject = z.object(fieldShape);
+function flatFieldKeys(fields) {
+  const out = [];
+  const childrenOf = (f) => {
+    const zones = f.config?.zones;
+    if (zones?.nonRepeatable) return zones.nonRepeatable;
+    if (zones?.repeatable?.fields) return zones.repeatable.fields;
+    return f.fields ?? [];
+  };
+  for (const raw of Array.isArray(fields) ? fields : []) {
+    const f = raw;
+    if (typeof f?.key === "string" && f.key.trim()) out.push(f.key.trim());
+    for (const raw2 of childrenOf(f)) {
+      const c = raw2;
+      if (typeof c?.key === "string" && c.key.trim()) out.push(c.key.trim());
+    }
+  }
+  return out;
+}
+function duplicateKeys(keys) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const k of keys) seen.set(k, (seen.get(k) ?? 0) + 1);
+  return [...new Set(keys)].filter((k) => (seen.get(k) ?? 0) > 1);
+}
+function duplicateKeyFailure(dupes) {
+  return `Duplicate API ID${dupes.length === 1 ? "" : "s"}: ${dupes.map((k) => `'${k}'`).join(", ")}. API IDs share ONE flat namespace across the whole model \u2014 a field inside a group must not reuse a key used by another field or group. Prefix each key with its section and retry (e.g. 'hero_title' and 'pricing_title', never 'title' in both).`;
+}
 function toFields(fs) {
   return (fs ?? []).map(toField);
 }
+function proseType(f) {
+  if (f.type !== "text") return f.type;
+  return f.richText === false ? "text" : "richtext";
+}
 function toField(f) {
   const base = {
     key: f.key,
@@ -2457,7 +2492,7 @@ function toField(f) {
   }
   return {
     ...base,
-    type: f.type,
+    type: proseType(f),
     ...f.options ? { options: f.options } : {},
     ...f.config ? { config: f.config } : {}
   };
@@ -2717,6 +2752,7 @@ function buildToolDefs(deps) {
   const getLayoutInput = z.object({
     scope: z.enum(["global", "page"]).default("global"),
     pageId: z.string().min(1).optional().describe("page id or slug; required for page scope"),
+    copy: z.enum(["draft", "published"]).optional().describe("which copy to read; default draft. Verifying a publish MUST read copy:'published' and check the response's copy echo \u2014 the draft is never a publish receipt (FLO-1188)."),
     projectId: z.string().min(1).optional().describe("required only for a workspace-scoped grant")
   });
   const layoutBinding = z.object({ inputId: z.string().min(1), fieldId: z.string().min(1) });
@@ -2803,6 +2839,83 @@ function buildToolDefs(deps) {
     slug: slug.describe("url-safe unique slug (lowercase letters/numbers/hyphens)"),
     projectId: z.string().min(1).optional().describe("only needed for a workspace-wide key")
   });
+  const sectionEvidenceProjectId = z.string().min(1).max(64).describe("exact project id from get_project (not a slug); Section evidence is project-local and never reusable across projects");
+  const sectionId = z.string().uuid().describe("Section definition id from Section Studio");
+  const sectionVersion = z.number().int().positive().describe("exact Section schema version implemented or tested");
+  const sha256 = z.string().regex(/^[0-9a-f]{64}$/i, "Expected a SHA-256 hex digest");
+  const sectionViewport = z.object({
+    name: z.string().trim().min(1).max(64),
+    width: z.number().int().min(240).max(7680),
+    height: z.number().int().min(240).max(7680)
+  });
+  const sectionEvidenceDigest = z.string().regex(/^(?:sha256:)?[0-9a-f]{64}$/i, "Expected a SHA-256 digest");
+  const nonEmptyDescriptor = z.record(z.string(), z.unknown()).refine((value) => Object.keys(value).length > 0, "Descriptor cannot be empty");
+  const sectionRequestId = z.string().uuid().describe("durable Section validation request id returned by list_section_validation_requests or the dashboard");
+  const sectionHttpUrl = z.string().url().max(2048).refine((value) => {
+    try {
+      const protocol = new URL(value).protocol;
+      return protocol === "http:" || protocol === "https:";
+    } catch {
+      return false;
+    }
+  }, "Expected an HTTP or HTTPS URL");
+  const sectionValidationViewport = sectionViewport.extend({
+    status: z.enum(["passed", "failed"]),
+    evidenceDigest: sectionEvidenceDigest
+  });
+  const submitSectionManifestInput = z.object({
+    projectId: sectionEvidenceProjectId,
+    requestId: sectionRequestId.optional().describe("include when fulfilling a claimed dashboard request so the evidence is bound to that exact run"),
+    sectionId,
+    version: sectionVersion,
+    apiId: z.string().regex(/^[a-z][A-Za-z0-9]*$/, "Use lower camelCase").max(100),
+    schemaHash: sha256.describe("exact SHA-256 hex hash shown for this Section version"),
+    commitSha: z.string().regex(/^[0-9a-f]{7,64}$/i).describe("git commit containing the implementation"),
+    loader: nonEmptyDescriptor.describe("non-empty serializable loader descriptor emitted by the repo build; never executable code"),
+    previewAdapter: nonEmptyDescriptor.describe("non-empty serializable adapter descriptor for the customer's real app shell; never executable code"),
+    nativeViewports: z.array(sectionViewport).max(20).optional().describe("the customer's named responsive viewports; BetterCMS also enforces Desktop 1440x900, Tablet 768x1024, and Mobile 390x844")
+  });
+  const submitSectionValidationInput = z.object({
+    projectId: sectionEvidenceProjectId.describe("exact project id from get_project (not a slug); must match the manifest's project"),
+    requestId: sectionRequestId.optional().describe("same claimed request id used for the manifest; binds and terminalizes that run"),
+    sectionId: sectionId.describe("exact Section definition id"),
+    version: sectionVersion,
+    manifestId: z.string().uuid().describe("manifest id returned by submit_section_manifest; it pins the schema hash and commit SHA"),
+    status: z.enum(["passed", "failed"]).describe("the actual result of the external repo/app-shell validation"),
+    fixtureHash: sha256.describe("SHA-256 hex hash of the canonical preview dataset and stress fixtures used"),
+    evidenceDigest: sectionEvidenceDigest.describe("SHA-256 digest of the immutable validation evidence bundle (screenshots/report/results)"),
+    appShell: z.object({
+      kind: z.literal("actual-app"),
+      identifier: z.string().trim().min(1).max(255),
+      url: sectionHttpUrl.optional()
+    }).describe("the real customer application shell used for the validation run"),
+    viewportResults: z.array(sectionValidationViewport).min(1).max(23).describe("one signed result for every required and native manifest viewport")
+  });
+  const listSectionValidationRequestsInput = z.object({
+    projectId: sectionEvidenceProjectId,
+    limit: z.number().int().min(1).max(100).optional()
+  });
+  const claimSectionValidationRequestInput = z.object({
+    projectId: sectionEvidenceProjectId,
+    requestId: sectionRequestId,
+    commitSha: z.string().regex(/^[0-9a-f]{7,64}$/i).describe("exact git commit the agent will inspect and validate; evidence must use this same commit"),
+    providerRunId: z.string().trim().min(1).max(255).optional(),
+    providerRunUrl: sectionHttpUrl.optional().describe("optional HTTP(S) link to the user's external agent run")
+  });
+  const completeSectionValidationRequestInput = z.object({
+    projectId: sectionEvidenceProjectId,
+    requestId: sectionRequestId,
+    manifestId: z.string().uuid().optional(),
+    validationRunId: z.string().uuid().optional()
+  });
+  const failSectionValidationRequestInput = z.object({
+    projectId: sectionEvidenceProjectId,
+    requestId: sectionRequestId,
+    errorCode: z.string().trim().regex(/^[A-Z][A-Z0-9_]*$/).max(100),
+    errorMessage: z.string().trim().min(1).max(2e3),
+    providerRunId: z.string().trim().min(1).max(255).optional(),
+    providerRunUrl: sectionHttpUrl.optional().describe("optional HTTP(S) link to the user's external agent run")
+  });
   function lifecycleTools() {
     const def = (name, title, description, shape, run) => ({
       name,
@@ -3063,6 +3176,13 @@ function buildToolDefs(deps) {
           return ok("Recorded the authoring architecture.", await data(c, "PATCH", `/management/projects/current/authoring-preference`, { preference }));
         }
       ),
+      def(
+        "set_binding_mode",
+        "Set how the site's bindings are resolved",
+        "Switch this project between the two binding resolvers, from the NEXT release on. `declaredBindings: true` makes the annotator trust the template's own data-bcms-field / data-bcms-props and never guess from rendered text \u2014 the durable state; `false` returns to text-matching, which works once (at import, when the CMS values equal the built copy) and breaks the first time anyone edits a value. Call it ONLY after every page's copy is declared in the template: undeclared fields stop being editable. The order is push \u2192 release \u2192 get_binding_report shows mode 'text-match' with 0 unmatched \u2192 set_binding_mode \u2192 release again \u2192 get_binding_report shows mode 'declared'. Flipping back is the same call. REQUIRES a project-scoped connection carrying the artifact:write scope \u2014 the same authority that deploys the site \u2014 because this decides what every future release does to every page; a workspace-wide grant is refused with 403. See section 13 of the bettercms://playbook/schema resource.",
+        z.object({ declaredBindings: z.boolean().describe("true = trust the template's declared bindings; false = text-match (the default)") }).shape,
+        async (c, a) => ok("Recorded the binding mode.", await data(c, "PATCH", `/management/projects/current/binding-mode`, { declaredBindings: a.declaredBindings }))
+      ),
       def(
         "clone_project",
         "Clone a project",
@@ -3172,6 +3292,13 @@ function buildToolDefs(deps) {
         z.object({}).shape,
         async (c) => ok("Next steps.", await data(c, "GET", `/management/insights/next-steps`))
       ),
+      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.",
+        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 })}`))
+      ),
       def(
         "get_analytics_overview",
         "Get traffic overview",
@@ -3241,6 +3368,102 @@ function buildToolDefs(deps) {
         z.object({ jobId: z.string().min(1) }).shape,
         async (c, a) => ok("Job rejected.", await data(c, "POST", `/management/bulk/jobs/${s(a.jobId)}/reject`))
       ),
+      def(
+        "list_section_validation_requests",
+        "List queued Section validation requests",
+        "Poll for user-agent Section implementation-validation requests in this exact project. BetterCMS cannot push work into an ordinary MCP client: call this explicitly, claim one request, inspect and run the customer's real repository/app shell, then submit request-bound evidence and complete it. Returns only unclaimed user-agent requests; it never exposes another project.",
+        listSectionValidationRequestsInput.shape,
+        async (c, a) => ok("Queued user-agent Section validation requests.", await data(
+          c,
+          "GET",
+          `/projects/${s(a.projectId)}/section-evidence/implementation-requests${q({ limit: a.limit })}`
+        ))
+      ),
+      def(
+        "claim_section_validation_request",
+        "Claim a Section validation request",
+        "Atomically claim one queued user-agent request and pin the exact git commit you will inspect. Claim BEFORE submitting evidence. BetterCMS records coordination only; all customer code and responsive checks must run in the user's repository and real app shell.",
+        claimSectionValidationRequestInput.shape,
+        async (c, a) => ok("Section validation request claimed.", await data(
+          c,
+          "POST",
+          `/projects/${s(a.projectId)}/section-evidence/implementation-requests/${s(a.requestId)}/claim`,
+          {
+            commitSha: a.commitSha,
+            providerRunId: a.providerRunId,
+            providerRunUrl: a.providerRunUrl
+          }
+        ))
+      ),
+      def(
+        "complete_section_validation_request",
+        "Complete a Section validation request",
+        "Complete a claimed request only after submit_section_manifest and submit_section_validation have bound exact, passed evidence to the same requestId and pinned commit. This cannot grant the separate human Visual Approval.",
+        completeSectionValidationRequestInput.shape,
+        async (c, a) => ok("Section validation request completed.", await data(
+          c,
+          "POST",
+          `/projects/${s(a.projectId)}/section-evidence/implementation-requests/${s(a.requestId)}/complete`,
+          { manifestId: a.manifestId, validationRunId: a.validationRunId }
+        ))
+      ),
+      def(
+        "fail_section_validation_request",
+        "Fail a Section validation request",
+        "Truthfully close a claimed request when the renderer, validation command, app shell, or required evidence is missing or fails. This path intentionally works without a manifest so 'not implemented' is representable instead of being reported as passed or left queued forever.",
+        failSectionValidationRequestInput.shape,
+        async (c, a) => ok("Section validation request failed.", await data(
+          c,
+          "POST",
+          `/projects/${s(a.projectId)}/section-evidence/implementation-requests/${s(a.requestId)}/fail`,
+          {
+            errorCode: a.errorCode,
+            errorMessage: a.errorMessage,
+            providerRunId: a.providerRunId,
+            providerRunUrl: a.providerRunUrl
+          }
+        ))
+      ),
+      def(
+        "submit_section_manifest",
+        "Submit a Section implementation manifest",
+        "Record the implementation manifest produced for one exact Section schema version by CI or an agent running INSIDE the user's repository. BetterCMS does not execute customer code: inspect/build the real renderer in the user's app shell first, then submit its exact API ID, schema hash, commit SHA, loader, preview adapter, and native responsive viewports. Requires a project-scoped artifact:write credential. This records evidence only; it does not validate the implementation and cannot create human Visual Approval.",
+        submitSectionManifestInput.shape,
+        async (c, a) => ok("Section implementation manifest recorded.", await data(
+          c,
+          "POST",
+          `/projects/${s(a.projectId)}/section-evidence/sections/${s(a.sectionId)}/versions/${a.version}/manifests`,
+          {
+            requestId: a.requestId,
+            apiId: a.apiId,
+            schemaHash: a.schemaHash,
+            commitSha: a.commitSha,
+            loader: a.loader,
+            previewAdapter: a.previewAdapter,
+            nativeViewports: a.nativeViewports
+          }
+        ))
+      ),
+      def(
+        "submit_section_validation",
+        "Submit a Section validation result",
+        "Record a real validation result for one exact Section schema version and manifest. Run the component in the user's repository and real app shell across the canonical preview dataset, AI stress fixtures, and required/native viewports BEFORE calling this tool; BetterCMS never runs that customer code. Pass status 'passed' only when those checks actually passed, otherwise 'failed'. The manifest pins schemaHash and commitSha; fixtureHash and evidenceDigest pin the tested data and immutable evidence bundle. Requires project-scoped artifact:write and cannot create the separate human Visual Approval required for publication.",
+        submitSectionValidationInput.shape,
+        async (c, a) => ok("Section validation result recorded.", await data(
+          c,
+          "POST",
+          `/projects/${s(a.projectId)}/section-evidence/sections/${s(a.sectionId)}/versions/${a.version}/validations`,
+          {
+            requestId: a.requestId,
+            manifestId: a.manifestId,
+            status: a.status,
+            fixtureHash: a.fixtureHash,
+            evidenceDigest: a.evidenceDigest,
+            appShell: a.appShell,
+            viewportResults: a.viewportResults
+          }
+        ))
+      ),
       def(
         "get_deploy_status",
         "Get deploy/build status",
@@ -3296,11 +3519,13 @@ 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. That tree is the page's SCHEMA \u2014 what it holds. " + SECTION_DOCTRINE,
+        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. \u{1F534} Every field key must be UNIQUE ACROSS THE WHOLE TREE \u2014 the namespace is flat, so 'title' cannot appear in two sections; prefix each with its section ('hero_title', 'faq_title'). Prose fields (headings, body copy, descriptions) are created as RICH TEXT by default; pass richText:false for values that must stay bare strings \u2014 hrefs, slugs, ids, emails. That tree is the page's SCHEMA \u2014 what it holds. " + SECTION_DOCTRINE,
         inputSchema: createPageInput.shape
       },
       handler: guard(
         async (args) => withClient(async (client) => {
+          const dupes = duplicateKeys(flatFieldKeys(args.fields));
+          if (dupes.length > 0) return fail(duplicateKeyFailure(dupes));
           const page = await client.createPage({
             title: args.title,
             slug: args.slug,
@@ -3326,6 +3551,8 @@ function buildToolDefs(deps) {
       },
       handler: guard(
         async (args) => withClient(async (client) => {
+          const modelDupes = duplicateKeys(flatFieldKeys(args.fields));
+          if (modelDupes.length > 0) return fail(duplicateKeyFailure(modelDupes));
           const model = await client.createModel({
             name: args.name,
             slug: args.slug,
@@ -3350,9 +3577,8 @@ function buildToolDefs(deps) {
       handler: guard(
         async (args) => withClient(async (client) => {
           const model = await client.getModel(args.modelId);
-          if (model.fields.some((f) => f.key === args.key)) {
-            return fail(`Field '${args.key}' already exists on model '${model.name}'.`);
-          }
+          const dupes = duplicateKeys([...flatFieldKeys(model.fields), args.key]);
+          if (dupes.length > 0) return fail(duplicateKeyFailure(dupes));
           const updated = await client.updateModel(args.modelId, {
             fields: [...model.fields, toField(args)]
           });
@@ -3596,13 +3822,13 @@ function buildToolDefs(deps) {
     {
       name: "get_layout",
       config: {
-        title: "Get the project or page Layout draft",
-        description: "Read the Global Layout or one page's Layout override, including its optimistic revision. Always read this before update_layout.",
+        title: "Get the project or page Layout",
+        description: "Read the Global Layout or one page's Layout override, including its optimistic revision. Always read this before update_layout. copy:'published' reads the published copy \u2014 the only honest receipt for a publish claim.",
         inputSchema: getLayoutInput.shape
       },
       handler: guard(async (args) => withClient(async (client) => {
         const layout = await client.getManagedLayout(args);
-        return ok(`${layout.scope === "global" ? "Global" : `Page ${layout.pageSlug}`} Layout draft at revision ${layout.revision}.`, layout);
+        return ok(`${layout.scope === "global" ? "Global" : `Page ${layout.pageSlug}`} Layout ${args.copy === "published" ? "PUBLISHED copy" : "draft"} at revision ${layout.revision}.`, layout);
       }))
     },
     {
@@ -3980,19 +4206,163 @@ 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
-    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
+    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.
+    3. Make the chrome ITSELF editable by speaking the layout grammar: the nav/footer
+       elements declare \`data-bcms-layout-section="navigation"\` / \`"footer"\`, and each
+       CMS-backed text inside them a \`data-bcms-layout-field="layout:<sectionId>:<fieldId>"\`
+       marker (fieldId is the field's REAL id, verbatim \u2014 production layout ids are
+       section-prefixed and dotted, e.g. \`footer.tagline\`, so the marker reads
+       \`layout:footer:footer.tagline\`) \u2014 the canvas then gives them hover chrome, the
+       Layout side panel, and
+       double-click editing, writing to the project Layout store (never the page).
+       The address reaches INSIDE structured fields by walking the schema: a group's text
+       sub appends its slug (\`layout:navigation:navigation.cta.label\`), a repeater row its
+       STORED index then the slug (\`layout:navigation:navigation.links.0.label\`), nesting
+       as deep as the schema goes (\`layout:footer:footer.link-groups.0.links.1.label\`).
+       Three rules, each one a measured defect when broken:
+       a. a field rendered by TWO elements gets a marker on BOTH \u2014 the editor keeps the copies
+          in sync, and a marker on only one leaves the other stale;
+       b. PROVENANCE \u2014 mark an element only when the LAYOUT supplied its value; a marker
+          over a fallback/singleton-sourced string opens an editor for a row that does not
+          exist;
+       c. row markers use the value's STORED index (a row you filtered out of the render
+          still occupies its slot), or the edit lands on the wrong row.
+       Text/longtext leaves edit inline; link/select/image leaves are side-panel-only by
+       design (their formats need a real control). THE DOCTRINE: every string a marketer
+       can see must be addressable \u2014 no marker means read-only on the canvas, so an
+       unmarked CMS-backed string is a defect, not a style choice.
+    4. 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.
 
+**Structural drafts can render on the real site too \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).
+
 **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.
+
+**\xA712 \u2014 RECEIPTS: a claim about published state needs a read of the PUBLISHED copy.** The
+doctrine this encodes cost a real incident (FLO-1188): a publish was verified against the
+draft for ~50 minutes because the reader silently returned the draft, and every check was
+green on the wrong document. Three rules, none optional:
+    1. NEVER verify a write by re-reading the store you wrote. Draft writes verify against
+       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.
+    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.
+    3. A tool param the schema does not declare is SILENTLY DROPPED, not rejected. If a
+       call's behavior doesn't change when you change a param, treat the param as dead and
+       verify through an independent channel before trusting any result built on it.
+
+## 13. Convert an imported repo into a CMS-backed, editable site
+
+\xA711 says a deploy does not make a site editable. This is the recipe that does, and it ends in a
+receipt you can read: \`get_binding_report\` says \`mode: "declared"\` with zero unmatched paths.
+
+**Scope, before you start.**
+
+(a) This is the FIELD-driven conversion \u2014 page fields and collections. If the human answered
+\`components\` at the \xA710 gate, go to \xA710's recipe instead: a component's editing surface is its
+declared \`props\`, and those bindings are NOT what \`get_binding_report\` walks.
+
+(b) It works for any framework that emits STATIC HTML, because the binding contract is plain
+HTML attributes \u2014 the annotator, the injector and the canvas stamper never see your source.
+There are SDK helpers for Astro and Next. A Node-runtime site (\`bcms-runtime.json\`) edits on
+the canvas but skips release annotation and publish-time injection, because there is no HTML on
+disk to annotate. Copy rendered on the client must carry the attributes in the HYDRATED DOM,
+and only the canvas sees it \u2014 a release scan cannot.
+
+**If you know Sanity, this is the same shape under different names:**
+
+    defineType schema in code   ->  content models / page fields (create_content_model,
+                                    add_page_field, or bcms-content.json "schema")
+    TypeGen                     ->  @bettercms-ai/codegen
+    GROQ query in the page      ->  @bettercms-ai/sdk read client, or the bcms-content.json
+                                    build snapshot
+    <PortableText> body         ->  @bettercms-ai/richtext portableTextToHtml, field type
+                                    'document'
+    data-sanity / stega         ->  data-bcms-field + data-bcms-kind (<BcmsField>), stega on
+                                    draft reads
+    Presentation tool overlays  ->  the visual editor canvas, framing your own build
+
+**The steps.**
+
+1. \`pull_project_source\` (or clone the \`github\` remote it returns). Read the SOURCE. Never
+   reconstruct content from the deployed HTML \u2014 that is how a site ends up bound to a copy of
+   its own stale build.
+2. Decide the architecture WITH the human (\xA710) and record it: \`set_authoring_preference\`.
+3. Register the schema. Per route: \`create_page\` + \`add_page_field\` (text / longtext /
+   richtext / image / array groups). Per repeated content type: \`create_content_model\`, with a
+   \`document\` body for articles. Site chrome goes through \`update_layout\`; images through
+   \`create_media_upload\` / \`upload_asset\`, then reference the CMS URL. The repo-owned
+   alternative to calling these one by one is a committed \`bcms-content.json\` carrying a
+   \`schema\` block, which seeds models, pages and entries at connect time \u2014 the \`defineType\`
+   analogue.
+4. Seed the entries with the copy EXACTLY as the source renders it (\`set_page_content\`,
+   \`create_content_entry\`). Prose goes in as Portable Text arrays (\`_type: "block"\`); never
+   markup inside a \`text\` field.
+   **Prose MIGRATED from another CMS needs one extra check.** Every block's \`_type\` must be one
+   this platform stores \u2014 \`block\`, or \`bcmsBlock\` carrying a \`schemaKey\` such as
+   \`builtin:table\` \u2014 and a foreign node (a Sanity-shaped \`{_type:"table", rows:[{cells}]}\` is
+   the one that has actually happened) is not merely unrendered: it has no component here, so it
+   vanishes from the HTML every delivery surface reads while the stored value still looks whole.
+   Verify each \`_type\` against the schema before you write, not after.
+5. Codemod the templates. Read each value from the CMS (\`@bettercms-ai/astro\` /
+   \`@bettercms-ai/next\` client, or the \`bcms-content.json\` build snapshot), KEEP the in-code
+   copy as the fallback, and declare the binding on the element that already renders it.
+   Prefer schema-derived bindings \u2014 the TypeGen analogue:
+   \`npx @bettercms-ai/codegen --bindings-out src/bettercms.bindings.generated.ts\`, then spread
+   \`{...bcms.home.hero.title}\` / \`{...bcms.blog.features.$(i)}\`. The hand form is
+   \`data-bcms-field="<path>"\` (plus \`data-bcms-kind="richtext"|"image"\`), \`data-bcms-props\`
+   for an \`href\` / \`alt\` / \`src\`, the \xA711 layout markers for nav and footer, and
+   \`<div data-bcms-field="body" data-bcms-kind="document">\` around a Portable Text render.
+   Bind CONDITIONALLY (\`fromCms ? path : undefined\`) so a fallback row is never bound. A value
+   rendered in N places carries the binding on ALL N \u2014 the editor keeps the copies in sync.
+   **Read the LIVE SCHEMA before you bind \u2014 \`get_page\` / \`get_content_model\`, never the
+   delivery snapshot.** A field nobody has authored yet is simply ABSENT from the payload, so a
+   snapshot cannot tell "this field does not exist" from "this field is empty": bind against it
+   and you declare a path for a \`cover\` field that was never created, which the report then
+   reports as broken forever. The schema is the list of what exists; the snapshot is only what
+   currently has a value.
+   **An index or listing route binds NOTHING.** The editor loads ONE entry per route, and an
+   index renders many, so a binding there addresses whichever entry the editor happened to
+   load. Bind each item's fields on that item's OWN route (\`/blog/<slug>\`); on the index,
+   render from the CMS and declare nothing.
+5b. **Where the content comes from at build time.** Two lanes, and they differ:
+    - GIT-CONNECTED (recommended for a converted site): the platform's provisioned workflow
+      writes \`bcms-content.json\` into the repo root before \`build\`, using the repo's
+      \`BCMS_API_KEY\` secret. Read that file, with in-code fallbacks so a local or CI build
+      without it still renders.
+    - ARCHIVE (\`deploy_project\` / \`deploy_from_upload\`): the sandbox build runs with no env
+      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.
+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. Now \`set_binding_mode
+   {declaredBindings: true}\` and release again (an empty commit is enough). Do not flip before
+   the report is clean: in declared mode an undeclared field simply stops being editable.
+7. **Receipts.** \`get_binding_report\` reads \`mode: "declared"\`, \`unmatched: []\`, and
+   \`bound > 0\`. That certifies one thing only \u2014 that every non-empty field 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 you call the page done. Then publish, and
+   fetch the live URL cache-busted (\xA712: publish and deploy are separate claims).
+   \`get_next_steps\` keeps reporting the gap until every one of these holds.
 `;
 
 // src/prompts.ts
@@ -4434,7 +4804,7 @@ On 401/403, the MCP key needs (re)authorizing.`
 
 // src/server.ts
 var SERVER_NAME = "bettercms";
-var SERVER_VERSION = "1.3.0";
+var SERVER_VERSION = "1.4.0";
 var SERVER_DISPLAY = {
   title: "BetterCMS",
   websiteUrl: "https://bettercms.ai",
@@ -4446,7 +4816,10 @@ var SERVER_DISPLAY = {
 function buildServer(deps) {
   const server = new McpServer(
     { name: SERVER_NAME, version: SERVER_VERSION, ...SERVER_DISPLAY },
-    { capabilities: { tools: {}, prompts: {}, resources: {} } }
+    {
+      capabilities: { tools: {}, prompts: {}, resources: {} },
+      instructions: "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."
+    }
   );
   server.registerResource(
     "schema-playbook",