@bettercms-ai/mcp 0.22.0 → 0.23.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

@@ -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,
@@ -3241,6 +3354,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 +3505,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 +3537,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 +3563,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 +3808,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);
       }))
     },
     {
@@ -3784,6 +3996,7 @@ function registerTools(server, deps) {
 import { z as z2 } from "zod";
 
 // src/playbook.ts
+var PLAYBOOK_URI = "bettercms://playbook/schema";
 var SCHEMA_PLAYBOOK = `# Designing a BetterCMS project
 
 Read this BEFORE creating anything. Confirm the shape with the user before you build it.
@@ -3981,17 +4194,65 @@ renders. Three consequences, each load-bearing:
          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
+    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 only one \u2014 the editor binds a
+          twice-carried field to neither;
+       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.
 `;
 
 // src/prompts.ts
@@ -4433,7 +4694,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",
@@ -4445,7 +4706,22 @@ var SERVER_DISPLAY = {
 function buildServer(deps) {
   const server = new McpServer(
     { name: SERVER_NAME, version: SERVER_VERSION, ...SERVER_DISPLAY },
-    { capabilities: { tools: {}, prompts: {} } }
+    {
+      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",
+    PLAYBOOK_URI,
+    {
+      title: "BetterCMS schema & components playbook",
+      description: "How to design a components-first BetterCMS project: components vs collections, section anatomy, sectionType variants, kind:'block' + modular fields, the 'document' article body, the draft->publish order, and what makes an imported site editable.",
+      mimeType: "text/markdown"
+    },
+    () => ({
+      contents: [{ uri: PLAYBOOK_URI, mimeType: "text/markdown", text: SCHEMA_PLAYBOOK }]
+    })
   );
   registerTools(server, {
     auth: deps.auth,