@bettercms-ai/mcp 0.63.2 → 0.64.0

package/dist/skills/bettercms/references/site-blueprints.md

@@ -0,0 +1,250 @@
+---
+title: "Site blueprints"
+description: "Route, collection and section plans per business type: portfolio, agency, corporate, SaaS/AI and ecommerce."
+---
+
+# Site blueprints by business type
+
+A route and content model that fits the business, while editor folders, public URLs and reusable
+components stay separate. A blueprint is a starting hypothesis, not permission to replace a
+working site's taxonomy. The platform rules behind each layer are in
+[content-modeling.md](content-modeling.md).
+
+## Contents
+
+- [Common decision process](#common-decision-process)
+- [Starter rules](#starter-rules)
+- [Deliverables](#deliverables)
+- Catalogs, read only the one that matches (a mixed site can use two, but give each page family
+  one route owner):
+  - [Portfolio](#portfolio-website): a person or studio presents selected work, services and a
+    contact path
+  - [Agency](#agency-website): services, sectors, proof and lead generation drive the site
+  - [Corporate](#corporate-website): several business units, regions, audiences, governance or
+    regulated content coexist
+  - [SaaS, AI, enterprise tech](#saas-ai-and-enterprise-technology-website): product,
+    solutions, industries, integrations, trust and education need separate models
+  - [Large ecommerce](#large-ecommerce-website): catalog, categories, products and shopping
+    journeys dominate; a Shopify-backed store also reads [shopify-headless.md](shopify-headless.md)
+
+Data-generated page families (glossary, integrations, locations): [programmatic-seo.md](programmatic-seo.md).
+
+## Common decision process
+
+1. Inventory existing public URLs, navigation, templates, source content, business goals,
+   locales, owners, analytics and design tokens. Keep established URLs and brand rules unless a
+   change is in scope.
+2. Give each family a **source of truth**: a BetterCMS page, a collection entry, an external
+   system (commerce, ATS, docs), or application runtime. Name its editorial owner and publishing
+   gate. Record capabilities BetterCMS does not have as gaps; never invent fields that imply
+   them.
+3. Produce a route matrix: pattern, purpose, static / list / detail, content source, template,
+   canonical, indexability, sitemap eligibility, and the redirect it replaces. A collection's
+   list is a page; its entries render through one dynamic detail page.
+4. Produce a model matrix: fields and groups, references, taxonomy, reusable sections, global
+   nav/footer, labels, and variants. Components for reusable presentation, collections for
+   entities with their own lifecycle. Whether bands become components or fields follows
+   `authoringPreference` from `get_project`, which only the owner answers.
+5. Propose **Content sidebar** folders for editor tasks, **component groups** for definitions,
+   and **media folders** for assets. None of these changes a URL. **URL page folders** do change
+   paths, and renaming one 301s its pages, so they need explicit review. Sidebar doctrine:
+   `bettercms://playbook/structure`.
+6. Define per-family SEO policy: one canonical target, real indexable content, native SEO
+   metadata (never modelled fields, §5b of `bettercms://playbook/schema`), structured data only
+   where visible facts support it, and the treatment of filters, search, pagination, drafts,
+   gated pages and deleted records. Pages marked noindex are left out of the generated sitemap.
+7. Validate one representative route per family and the edge cases: empty collection, long
+   title, unpublished detail, duplicate slug, moved URL, mobile nav, optional section, locale,
+   no-result state. Confirm edit, preview and public render, then the build and binding reports.
+
+## Starter rules
+
+- Reference page lists illustrate common shapes; do not create pages the business does not have.
+- Prefer a few stable, human-readable route patterns. The best URL is often the existing one.
+- Keep a slug unique within its route namespace; check static against dynamic paths and locales.
+  When a published URL changes, add a redirect (`create_redirect`).
+- Keep a dedicated 404 and access/error pages. Leave drafts, private areas, internal search,
+  parameter duplicates and 404s out of the sitemap.
+- Sitemaps hold absolute, canonical, indexable URLs; Google documents a limit of 50,000 URLs /
+  50 MB uncompressed per file. [Google sitemap guide](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap)
+- Content sidebar folders are navigation for editors. Public hierarchy comes from routes and
+  internal links, never from folder labels. [Google ecommerce site structure](https://developers.google.com/search/docs/specialty/ecommerce/help-google-understand-your-ecommerce-site-structure)
+- With locale variants, keep explicit equivalent-page mappings and one `hreflang`
+  implementation, verified in the rendered head. [Google localized versions](https://developers.google.com/search/docs/specialty/international/localized-versions)
+
+## Deliverables
+
+Return a route tree, route matrix, content and model matrix, folder plan, component inventory,
+sitemap and redirect policy, open ownership decisions, and a phased implementation plan. On a
+live project, implement only the scope the user asked for and verify the routes you touched.
+
+## Portfolio website
+
+Use this when the primary job is to show selected work and make an individual or small studio credible. First determine whether the work is private, client-approved, dated, or still under embargo.
+
+### Route and model starter
+
+| Family | Example path | BetterCMS model | Index and sitemap |
+|---|---|---|---|
+| Home | `/` | Static page with selected projects and clear contact action | Yes |
+| Work index | `/work/` | Static index page querying Projects | Yes if substantive |
+| Project detail | `/work/{slug}/` | Projects collection + one dynamic template | Published, approved projects only |
+| About / services | `/about/`, `/services/` | Static pages unless services need independent owners and detail pages | If public and useful |
+| Writing / speaking | `/writing/`, `/writing/{slug}/` | Optional collection and index | Published articles only |
+| Contact | `/contact/` | Static page + form | Usually yes |
+| Password/preview case study | Existing route | Other page or protected runtime route | No |
+
+Keep the existing work prefix if it is `/projects/`, `/case-studies/`, or another established route; route changes need a redirect map.
+
+### Editor structure
+
+Content sidebar: `Start here` (Home, About, Contact), `Portfolio` (Work index, Projects), `Writing` if used, `Site essentials` (legal/other). Component groups: `Globals`, `Portfolio` (project hero, gallery, outcomes), `Shared sections` (CTA, quote, logo strip). Media folders may separate approved client work, self-initiated work, portraits, and downloadable files. These folders do not determine URLs.
+
+Project entry fields: display title, slug, client display name, service/category references, summary, role, dates when relevant, hero image plus alt text, ordered gallery items with captions/alt, challenge, approach, verified outcomes, credits, related projects, SEO, approval/visibility state. Do not require a public client name, metric, or testimonial when consent is absent. Support anonymous case studies without accidentally exposing the original client in image filenames, alt text, schema, or social previews.
+
+Use repeatable gallery items rather than a long list of `image1` fields. Give each item a meaningful editor label and image metadata. Keep project-specific storytelling sections as instances; make hero/gallery/quote layouts reusable definitions with instance overrides.
+
+### Validation
+
+Check case-study consent, working gallery at different aspect ratios, captions, full-size media performance, downloadable file links, contact submission, related-work references, archived projects, and redirect behavior for renamed slugs. A portfolio with only a few projects does not need auto-generated service × industry pages.
+
+## Agency website
+
+Use when the site must explain services, prove results, and convert qualified leads. The key distinction from a portfolio is a durable offer taxonomy and repeatable proof linked to each offer.
+
+### Route and model starter
+
+| Family | Example path | Model and purpose |
+|---|---|---|
+| Home | `/` | Static overview, positioning, primary CTA |
+| Services index/detail | `/services/`, `/services/{slug}/` | Static index + Services collection only if multiple services have owners, proof, and maintained detail content; otherwise static pages |
+| Industries | `/industries/`, `/industries/{slug}/` | Optional collection; publish only distinct industry expertise |
+| Work index/detail | `/work/`, `/work/{slug}/` | Case studies collection and dynamic detail template |
+| Insights | `/insights/`, `/insights/{slug}/` | Editorial collection, authors, categories |
+| Agency | `/about/`, `/team/`, `/careers/` | Static or collection by update cadence |
+| Contact | `/contact/` | Form with routing/consent behavior |
+
+Use the established `/case-studies/`, `/blog/`, etc. when the current site already has them. A service × industry matrix should be created only for combinations with distinct evidence, offer, and maintenance owner; otherwise link the existing service and industry pages instead of generating thin duplicates.
+
+### Content relationships and components
+
+Cases reference services, industries, client permission state, outcome evidence, and optional quotes. Service pages reference relevant cases, deliverables, process, FAQ, and CTA. Industry pages reference services/cases and sector-specific language. Avoid duplicating client logos or metrics across pages: maintain permission and source context on the case/client record.
+
+Component groups: `Globals` (nav/footer), `Proof` (case card, metrics, testimonial), `Offers` (service card, process), `Conversion` (CTA, contact form), `Editorial`. Reuse definitions with page-specific props, and allow section order to vary by page. Editors should see grouped fields such as `Primary button → Label, Link`, `Proof item → Metric, Context, Source`.
+
+Content sidebar folders should match editor work: `Core pages`, `Services`, `Industries`, `Case studies`, `Insights`, `Company`. These are dashboard folders, not paths.
+
+### Validation
+
+Review lead form destination, attribution and consent, internal links from every offer to relevant proof, case-study rights, schema claims, duplicate service routes, old URL redirects, and mobile CTA visibility. Keep draft or client-confidential work out of sitemaps and public data feeds.
+
+## Corporate website
+
+Use for multiple audiences, brands, regions, business units, approval chains, or regulated statements. The main modeling problem is ownership: who can update a statement, which sites reuse it, and when it expires.
+
+### Route and model starter
+
+| Family | Example path | Owner and model |
+|---|---|---|
+| Corporate home | `/` | Global communications; static page |
+| Business units | `/businesses/{slug}/` | Collection if units share a template and lifecycle |
+| Products/services | Existing taxonomy | Collection or static pages by unit ownership |
+| Newsroom | `/news/`, `/news/{slug}/` | News collection, media contact, publish date |
+| Leadership | `/leadership/`, `/leadership/{slug}/` | People collection if profiles recur |
+| Careers | `/careers/` | Landing page; job details may remain in an ATS |
+| Investor / governance | `/investors/`, `/governance/` | Gated approval; files with version/date |
+| Policies and legal | `/privacy/`, `/terms/` | Static pages with accountable owner |
+| Contact / locations | `/contact/`, `/locations/{slug}/` | Form plus locations collection when needed |
+
+Do not copy ATS jobs, stock prices, investor filings, or regulated data into BetterCMS unless BetterCMS is deliberately the system of record. Preserve external systems and public links.
+
+### Governance and editor structure
+
+Record owner, reviewer, source of claim, effective date, review date, and version where these matter. Separate draft, legal-reviewed, approved, and published states with the project's own editorial board: read its stages and which one is the publish gate with `get_workflow_board` before `move_stage`, because stage keys are per project. Do not claim an approval stage exists if the board has none. Scope access and publishing by the product's real permissions. High-risk copy (financial figures, certifications, compliance claims, regulated products) needs a verified source and designated reviewer.
+
+Content sidebar: `Corporate pages`, `Business units`, `Newsroom`, `People`, `Investors`, `Legal`, `Regions` if used. Component groups: `Globals`, `Corporate identity`, `Business unit`, `Newsroom`, `Data/proof`. Distinguish sitewide global identity from unit-specific branding and local navigation. A shared global component should not overwrite an independently branded unit page.
+
+### Regions and languages
+
+Choose a deliberate URL strategy, such as `/{locale}/...` or regional domains. Keep locale-to-locale equivalent-page IDs, fallback behavior, canonical target, and language switcher destinations. Check what the connected project models for locales before planning; implement and verify `hreflang` output in the frontend, where the rendered head is decided. Do not auto-redirect by IP or index machine placeholders. Follow [Google's localized-page guidance](https://developers.google.com/search/docs/specialty/international/localized-versions).
+
+### Validation
+
+Test unit-specific nav/footers, ownership permissions, embargoed news, expiring files, superseded legal pages, regional links, localization fallbacks, 404/redirects, accessibility, and the published head for every major template. Separate search visibility from access control: `noindex` does not protect private information.
+
+## SaaS, AI, and enterprise technology website
+
+Use when a product site must explain a platform to multiple buyers and evaluators. Distinguish product truth, marketing interpretation, developer documentation, and live application behavior.
+
+### Route and model starter
+
+| Family | Example path | Suggested ownership |
+|---|---|---|
+| Home | `/` | Static marketing composition |
+| Product/platform | `/product/`, `/features/{slug}/` | Static overview; Features collection only if repeated and maintained |
+| Solutions | `/solutions/{slug}/` | Collection for distinct jobs-to-be-done/use cases |
+| Industries | `/industries/{slug}/` | Collection where sector-specific workflows/proof exist |
+| Integrations | `/integrations/{slug}/` | Collection with provider status, auth, capability, owner |
+| Customers | `/customers/{slug}/` | Case studies with approvals and proof sources |
+| Pricing | `/pricing/` | Static page or runtime-driven product data; one owner for actual pricing |
+| Resources | `/resources/{slug}/`, `/blog/{slug}/` | Editorial collections and their list pages |
+| Glossary | `/glossary/{term}/` | Definition collection with editorial gates |
+| Comparisons / alternatives | `/compare/{slug}/` | Dedicated reviewed model, never blind competitor templating |
+| Trust and legal | `/security/`, `/privacy/`, `/trust/` | Static pages or external trust center |
+| Docs / API | `/docs/...` | Often a separate docs system/repository; link rather than duplicate |
+| Conversion | `/demo/`, `/contact/` | Forms with routing, consent, and success states |
+
+These are options, not required pages. Keep existing routes and product naming. For a large enterprise site, consider ownership by product line/market and a shared navigation contract; avoid separate page schemas for identical layouts.
+
+### Model and section kit
+
+Entities: Solutions, Industries, Features, Integrations, Cases, Resources, Glossary Terms, and optional Comparisons. Use references across them so an integration or proof item updates once. Each entry needs an owner, lifecycle, canonical URL, native SEO metadata, and sufficient unique content. Integration entries need a clear status (live, beta, planned) and must never imply a planned connector is available.
+
+Shared sections: product hero, outcome grid, workflow steps, feature visual, integration grid, proof strip, case excerpt, FAQ, security/trust callout, pricing CTA. Keep a single component definition per visual family and use variants/instance overrides. Give buttons and media grouped editor controls. Expose only supported rich-text headings; a hero title may be plain text rendered as H1 while an article body may allow H2/H3, links, lists, and code if the renderer supports them.
+
+Content sidebar: `Core pages`, `Product`, `Solutions`, `Industries`, `Integrations`, `Customers`, `Resources`, `Trust`, `Other`. Component groups should reflect role, not route.
+
+### Search and AEO
+
+Build topic hubs and link related solution, industry, integration, case, and glossary pages. Only publish a specific solution × industry page when it adds differentiated workflow, evidence, and value. Answer questions directly with verifiable facts and useful context; do not fabricate FAQ, schema, or “AI answer” pages. Use [programmatic-seo.md](programmatic-seo.md) for generated page families and [Google's AI-search guidance](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide) for the current search-policy boundary.
+
+### Validation
+
+Verify product claims against shipped capability, integration statuses, pricing consistency, demo form routing, docs links, internal topic paths, glossary duplicates, comparison accuracy, rendering of code/rich text, and desktop/mobile navigation. Noindex preview, gated assets, and incomplete pages.
+
+## Large ecommerce website
+
+Use for a catalog-heavy site regardless of commerce engine. The core choice is the boundary between **commerce facts** and **editorial merchandising**.
+
+### Source-of-truth contract
+
+Products, variants, SKUs, price, availability, tax, orders, checkout, customer accounts, and fulfillment normally belong to the commerce platform. BetterCMS owns editorial landing pages, category storytelling, buying guides, banners, proof, and selected product-page content blocks. A CMS reference to a product uses a stable external ID plus a verified lookup; don't silently duplicate transactional fields into editable CMS text.
+
+### Route and model starter
+
+| Family | Example path | Index policy |
+|---|---|---|
+| Home and campaigns | `/`, `/campaigns/{slug}/` | Public, unique campaigns |
+| Catalog root / category | `/shop/`, `/collections/{slug}/` | Curated category pages with products and links |
+| Product | `/products/{slug}/` | Available public products; decide retired-product policy |
+| Brand | `/brands/{slug}/` | Only substantive brand pages |
+| Buying guides | `/guides/{slug}/` | Unique advice with product references |
+| Editorial | `/stories/{slug}/` | Published articles |
+| Search, cart, account, checkout | Runtime routes | Usually excluded from sitemap; private data protected |
+| Filters and sort | Parameters on category routes | Explicit crawl/index policy; avoid unbounded URL combinations |
+
+Keep existing paths if the store already uses another taxonomy. Decide whether unavailable products stay indexable, redirect to a successor, or return 404/410 based on permanence and user value. Do not redirect every missing product to the homepage.
+
+### Editor model and reuse
+
+Models: Campaigns, Buying Guides, optional Brand and Category editorial records, plus product references. Category merchandising groups can include hero, intro, featured products, editorial cards, filters, and FAQs. Components: global store nav, search, promo bar, product card, variant selector, add-to-cart, category hero, recommendation rail, cart feedback. Commerce controls remain functional code tied to live data; an editor can change allowed presentation and copy but must not create an unfulfillable cart action.
+
+Content sidebar: `Campaigns`, `Collections`, `Guides`, `Stories`, `Store pages`; group media by campaigns/editorial needs. Content sidebar folders never change a URL; URL page folders do, and renaming one 301s its pages, so do not turn category folders into URL folders unless a route change is intended.
+
+### Crawl and scale
+
+Provide crawlable category → subcategory → product links and paginated result URLs. Decide which facet combinations deserve dedicated curated landing pages; keep the rest out of the index/crawl space by an intentional policy. Do not rely on canonical alone to control a near-infinite faceted URL space. Keep canonical, internal link, and sitemap URLs consistent. Sitemaps should include only eligible canonical pages and split before protocol limits. Product price/availability markup must match the current displayed commerce data; validate variant markup against Google's current `ProductGroup` guidance. [Google ecommerce structure](https://developers.google.com/search/docs/specialty/ecommerce/help-google-understand-your-ecommerce-site-structure) · [Faceted navigation](https://developers.google.com/crawling/docs/faceted-navigation) · [Product variants](https://developers.google.com/search/docs/appearance/structured-data/product-variants)
+
+### Validation
+
+Test a product with several variants, a sold-out product, missing image, empty category, deep pagination, filter combinations, mobile search, currency/market change, cart handoff, and changed price after cache expiry. Verify that sitemap counts match eligible catalog records and that deleted routes/redirects do not strand internal links.

package/dist/skills/bettercms/references/site-review.md

@@ -0,0 +1,73 @@
+---
+title: "Site review"
+description: "A read-only launch review: what to check per route and how to report findings without fixing them."
+---
+
+# Read-only site review
+
+**Outcome.** An evidence-backed issue list, scoped to the actual project and revision, that a
+developer can reproduce and prioritise. Change no data or code during a review unless the user
+separately asks for repairs.
+
+## Establish a baseline
+
+Identify the project, source commit, import or release revision, hosting mode (`get_project`),
+public or staging URL, and expected route inventory. Then read the control plane and record when
+each report was generated:
+
+| Read | Tells you |
+|---|---|
+| `get_site_composition` | Which pages are made of sections, and which components they use |
+| `get_binding_report` | Per route: `mode` (`declared` or `text-match`), `coverage.pending`, and `refreshReason` when there is no current report |
+| `list_seo_issues` | Native SEO problems per page |
+| `get_component_readiness` | Per component: validation and Output state |
+| `list_forms` | Which forms exist and whether each is published |
+| `get_deploy_status` | The last build and release |
+| `get_next_steps` | What the platform itself still counts as unfinished |
+
+A binding report is created only by a BetterCMS release (a content apply later updates its Layout
+rows), so a headless site may never have one; `never-generated` is missing evidence, not a clean
+result. A green control plane cannot prove a route answers:
+fetch rendered pages too, cache-busted.
+
+Sample every **route class** (static, list, collection detail, 404 or protected, locale) and
+every **component family**. Include two instances of a reused component, one variant, one nested
+slot, the global nav and footer, long and empty content, and a custom Portable Text block when
+present. Widen the sample when a failure looks systematic.
+
+## Review dimensions
+
+| Dimension | Evidence to collect |
+|---|---|
+| Structure | Page / collection / entry classification, which of the four folder systems is used for what, route and redirect integrity |
+| Reuse | Definition, default, variant and instance ownership; override isolation; global chrome; slot limits |
+| Editability | Schema, stored value, reader, prop, bound leaf or attribute, preview, published output; intended fields against verified bindings |
+| Editor UX | Field types, allowed Portable Text controls, labels, grouping, defaults, required states, repeatable-item previews |
+| Design and media | Brand tokens, font loading, logo roles, asset delivery from the project's media origin, alt / caption / crop, desktop and mobile fidelity |
+| Behaviour | Forms and their destinations, keyboard and focus, navigation, accordion / modal / consent logic, custom code |
+| Discoverability | Native SEO, canonical and noindex, structured data matching visible content, sitemap and robots, internal links |
+| Delivery | Build, cache and revalidation, live status and content, draft isolation, secrets and the server/client boundary |
+
+Use automated checks where they answer a concrete question, and manual visual or editor checks
+where automation cannot show intent. Never edit production as a test. If an edit-to-render test
+needs a write, mark it unverified in a read-only review, or get the user's authorisation for a
+safe draft test.
+
+Useful anchors while reviewing: a draft form refuses public submissions (403), so a form that
+renders but is not published cannot take a lead; a headless project is never built by BetterCMS,
+so its proof is the external host's public response; a Content sidebar folder never changes a
+URL, while renaming a URL page folder 301s its pages.
+
+## Issue format and decision
+
+For each issue record severity (blocker, high, medium, low), the route / component / field,
+expected against observed, exact reproduction, evidence (link, screenshot, report time), likely
+owner, and a specific acceptance check. Separate a verified defect from an inference or missing
+evidence. Summarise coverage as verified intended editable fields divided by discovered intended
+editable fields, with exclusions listed separately.
+
+Recommend **ready**, **ready with named exceptions**, or **not ready**. A blocker includes a
+broken public route, lost content or reference, an unbound core editorial value, a form sending
+to the wrong destination, an exposed secret, or a live state that contradicts what the user
+intended. For each, give the smallest repair path and whether it belongs to code, CMS data, a
+platform capability, or a user decision.

package/dist/skills/bettercms/references/write-limits.md

@@ -0,0 +1,84 @@
+---
+title: "Write limits"
+description: "What the server checks on a content write (lengths, patterns, uniqueness, references, body size) and what it does not."
+---
+
+# Write limits: what the server checks on a content write
+
+Use this before you rely on a limit. "Exists" means the server refuses a bad value. "Does not
+exist" means the value is stored, so you are the check.
+
+## The write path
+
+Entry writes from the MCP and the Management API run `createEntry` / `updateEntry` in
+`src/lib/content/entry-write.ts`:
+
+1. Request schema (Zod). Failure: 400 with `{ errors }`, keyed by field, no `code`.
+2. Value normalisation (shapes below). Failure: a validation result with `errors`.
+3. Per-field value checks against the model. Failure: a validation result with `errors`.
+4. Uniqueness, inside the insert transaction. Failure: `kind: "unique_conflict"` with `conflicts`.
+
+The batch route reports the same two outcomes as `code: "UNIQUE_CONFLICT"` or `"VALIDATION"`.
+
+Rule: read `errors` by field key, fix exactly those fields, write again once.
+
+`update_content_entry` `data` REPLACES the entry's whole value object: an optional field left out
+is deleted. Send `merge: true` to lay `data` over the stored value by top-level key (a group or
+repeater you send still replaces that whole key). Pass `ifMatch` (the `optimisticVersion` from
+`get_content_entry`) so a 409 tells you someone wrote since your read; with `merge` it defaults to
+the version the merge read.
+
+## Limits that exist
+
+| Limit | Behaviour |
+|---|---|
+| `maxLength` / `minLength` in text field config | Counted in characters. An empty value is left to `required` |
+| `pattern` in text field config | Tested against every non-empty value |
+| Numeric limit config (`maxLength`, `minLength`, `min`, `max`, `step`) on model save | A numeric string (`"60"`) is stored as a number; an impossible value (`"abc"`, a negative length, `step: 0`, `min` above `max`, a pattern that does not compile) is refused with `FIELD_CONFIG_INVALID`, naming the field and the fix |
+| Repeater `maxItems` | Enforced when a number |
+| `select` value | Must be one of the field's options |
+| Rich text top-level `_type` | A name nothing renders is refused, naming `_type` and `_key`. Top level only — a foreign mark keeps its text unmarked, a foreign inline child renders nothing |
+| Request body | 260 MB for the whole server |
+
+## Limits that do not exist (you hold them)
+
+| Missing check | Rule for the agent |
+|---|---|
+| Limit config saved as a string before the model-save check existed | Write every numeric config value as a JSON number; re-save a model you find with string limits |
+| Modular (block) field `blockSlugs`, `minItems`, `maxItems` | Check the block list against the field config yourself before writing |
+| Reference existence on draft save and publish (shape only) | Read each referenced entry id before you write the reference |
+| Component `overrides` (any keys, any types; required props not enforced) | Write only declared prop keys with the declared type; fill every prop the component needs |
+| Size or depth of text, richtext and JSON values | Keep values to what the page renders; never paste whole documents into one field |
+| Publish re-validation (publish copies the draft to live) | Only publish a draft you wrote through the write path above |
+| Version restore re-validation (restore writes the stored snapshot) | After a restore, read the entry and write it back through `update_content_entry` so checks run |
+
+## Normaliser output shapes
+
+What you read back after a write:
+
+| Field | Stored shape |
+|---|---|
+| richtext | `{ format, value, html }` envelope |
+| image | `{ id, url, name, altText }`. An asset id or media URL resolves to its asset; a site-relative path resolves to the asset the build adopted; an external URL on a project-scoped write is fetched and stored as a new asset. Only when none of that works (fetch refused or failed, no project scope) is it kept as `{ url }` (plus `altText` if given) |
+| group / repeater (zoned) | Zone envelopes `{ nonRepeatable, repeatable }`, walked field by field |
+| repeater given a bare array | Wrapped as `{ repeatable: [...] }` |
+
+Rich text written as HTML or markdown may be stored in the older Lexical format depending on a
+server flag. Portable Text arrays are always stored as Portable Text
+([portable-text.md](portable-text.md)).
+
+A stored value of `{ html }` is the shape starter templates and `bcms-content.json` seed. Writes
+accept it and store the full envelope, so sending an entry's data back unchanged works. Do not
+write new rich text in that shape.
+
+## Other refusal codes that exist today
+
+| Area | Codes | Where described |
+|---|---|---|
+| Content sidebar structure | `NAV_SYSTEM_FOLDER`, `NAV_TYPE_MISMATCH`, `NAV_KIND_MISMATCH`, `NAV_PAGE_BOUND_MODEL`, `SCHEMA_ACCESS_REQUIRED` | the folder tool descriptions |
+| Hosting | `HEADLESS_NO_BUILD`, `HEADLESS_NEEDS_CUSTOM_HOST`, `HEADLESS_ARTIFACT_TARGET` | [frameworks.md](frameworks.md) |
+| Components | `COMPONENT_*` publish codes | [components.md](components.md) §4 |
+| Content models | `FIELD_CONFIG_INVALID` | this file |
+| Forms | `FORM_FIELD_INVALID`, `FORM_DEFINITION_INVALID`, `FORMS_WORKER_NOT_CONFIGURED`, `FORMS_WORKER_SECRET_UNSET`, `FORM_SUBMISSION_NOT_FOUND`, `FORM_SECRET_DASHBOARD_ONLY` | [forms-and-interactions.md](forms-and-interactions.md) |
+
+`SCHEMA_ACCESS_REQUIRED` (403): see the owner boundary in SKILL.md.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/mcp",
-  "version": "0.63.2",
+  "version": "0.64.0",
   "type": "module",
   "description": "BetterCMS MCP server — schema, content, forms + components authoring tools over the Management API, authed via OAuth device-code.",
   "bin": {
@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "@bettercms-ai/device-auth": "^0.2.0",
-    "@bettercms-ai/sdk": "^1.24.0",
+    "@bettercms-ai/sdk": "^1.25.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.3.6"
   },