@bettercms-ai/mcp 0.63.2 → 0.64.0

package/dist/skills/bettercms/references/localization.md

@@ -0,0 +1,81 @@
+---
+title: "Localization"
+description: "Document-per-locale translations (locale, translationOf, translate_entry, delivery translations), URL-prefixed locale copies of imported builds, Layout locale variants, locale-unvarianted, hreflang, and what never to model."
+---
+
+# Localization
+
+**Outcome.** A multilingual site keeps every language rendering, each language's copy is
+editable, and nothing invents a locale model the platform does not read.
+
+Two things are called a "language" here, and they are separate:
+
+- **A translation** is its own entry or page row, one per locale: `locale` is its BCP-47 tag (one
+  of the project's locales; null = the default language) and `translationOf` is the SOURCE row's
+  id. Each has its own slug, draft and publish state.
+- **A locale copy of an imported build** is a URL prefix (`/fr`, `/pt-br`) proven by the page's own
+  `<html lang>`. It is how a converted site's languages arrive, before anyone models them.
+
+## 1. What exists
+
+| Piece | How it works |
+|---|---|
+| The project's locales | `localeConfig.locales`, set by the owner in the dashboard (project settings). A `locale` outside it is refused with 400; an empty list means a single-language project |
+| Translate an entry with AI | `translate_entry` { entryId, targetLocale, slug?, fields? } creates the translation as a DRAFT with `locale` and `translationOf` set (AI credits: 402/403 when out or not on the plan). Text and longtext are translated; rich text and documents are copied for you to translate; `meta` lists which. `409 locale_conflict`: that translation exists, so edit it instead |
+| Create one by hand | `create_content_entry` or `create_page` with `locale` and `translationOf` = the source's id, never another translation's. One row per locale per source (a second is `409 locale_conflict`); `update_content_entry` / `update_page` change either, null clears |
+| Find them | `list_content_entries` `where: { locale: 'fr' }`; default-language rows have a null `locale`, so they match `{ locale: { ne: 'fr' } }`, never `eq` |
+| Deliver them | Every delivered entry carries `locale`, `translationOf` and `translations`: `[{ id, locale, slug }]` of its group's other PUBLISHED rows (drafts only when previewing). A delivered page carries `locale` and `translationOf` |
+| Translate one string | `write_content` with `action: "translate"` and `targetLang` returns the text; apply it with `set_page_content` or `update_content_entry` |
+| Locale copy of an imported page | A page whose route opens with a language prefix its own `<html lang>` confirms (`/fr` on a French page). The prefix is proven by the page's language, never by the segment's shape: `/de` is a locale only on a German page |
+| Componentizing a locale copy | `get_componentize_plan` places `/fr` on its default-locale twin's components, band by band, when each pair holds the same prop types in the same order; a mismatched band stays its own section. `componentize_sections` `joinTwins` moves older copies onto their twin's components |
+| Layout locale variants | A Global Layout Section can have a variant per locale (`navigation--fr`). A page renders the variant whose locale is its route's first segment, else the base |
+| `locale-unvarianted` | A `get_binding_report` unmatched reason: the route resolved in a locale, the Section has no variant for it, and the base still renders there. Named, never written |
+
+Import does not derive deeper locale routes (`/fr/about`) into foldered pages or collections: a
+language prefix is a whole site, not a URL folder, so those routes keep serving from the build.
+Why it matters: an edit to `/about` never reaches `/fr/about`, and nothing edits `/fr/about`
+until it is a page. Say so in the coverage report.
+
+## 2. Never model
+
+- **No `language`, `locale` or `lang` field** on a model, page or component, and no
+  `translations` reference field between entries. The language is the native `locale`, the link
+  is the native `translationOf`, and delivery derives `translations` from them.
+- **No hreflang, alternate-URL or canonical-per-language field.** SEO is native
+  ([seo.md](seo.md)), and the native columns have no locale slot.
+- **No per-language copy of a field** (`titleFr`, `titleEn`). It doubles every edit and leaves
+  the page's language implicit in a key name.
+
+## 3. Where hreflang comes from
+
+The frontend writes the `<head>` links. For each entry, render `<link rel="alternate" hreflang="…">`
+for itself and for every row in its delivered `translations` (the locale is the tag, the slug
+builds the URL on the site's own route pattern), plus `x-default` for the default-language row.
+Hosted `<head>` output emits none.
+
+The hosted sitemap does emit them. Every listed page or entry in a translation group (the source
+plus its `translationOf` rows) carries `<xhtml:link rel="alternate" hreflang>` for each listed
+sibling, itself included, plus `x-default` for the source. A row with no `locale` takes the
+project's `localeConfig.defaultLanguage`; with neither, it gets no link of its own. Unpublished
+and noindex siblings are not listed, so they get no link either. Check the live `sitemap.xml`.
+
+## 4. Workflow
+
+For a site modelled in the CMS:
+
+1. Confirm the owner has set the project's locales; you cannot.
+2. Per source entry, `translate_entry` into each locale (or create the row by hand), then
+   translate the copied rich text with `write_content` and write it with `update_content_entry`.
+3. Review each draft with the user, publish it (`publish_entries` takes many), and check the
+   source's delivered `translations` lists it.
+4. Emit hreflang from `translations` in the frontend (§3) and fetch each language's URL.
+
+For a multilingual import:
+
+1. List the prefixes the build serves and confirm each page's `<html lang>` matches its prefix.
+2. Componentize the default language first; the plan then places each locale copy on its twin.
+3. Read `get_binding_report` on each prefixed route: `locale-unvarianted` rows are the Layout
+   Sections still showing the default language there. `update_layout` takes no locale, so name
+   those Sections to the user rather than writing translated copy onto the base.
+4. Translate with `write_content`, apply, publish, and fetch each prefixed URL.
+5. Report the routes that stay build-only (deeper locale routes) with their count.

package/dist/skills/bettercms/references/media-and-brand.md

@@ -0,0 +1,142 @@
+---
+title: "Brand kit and media"
+description: "Brand tokens, fonts, logo kit, image sizing and focal point, SVG and video rules, and the media host."
+---
+
+# Brand kit, section styles and media
+
+**Outcome.** An imported site keeps its appearance, and editors change the intended brand and
+media controls through one coherent system instead of scattered CSS values.
+
+## Audit sources and the rendered design
+
+Inspect CSS variables, the Tailwind or theme config, design-token files, `@font-face`, layout
+components, media directories, responsive assets and computed styles on representative routes.
+Compare desktop and mobile screenshots. Record where each proposed token came from and how often
+it is used. One colour on one button is not a brand identity.
+
+Build a token inventory: role, source value, proposed BetterCMS value, affected components,
+confidence, approval status. Cover colours, type families, weights and scale, spacing, container
+widths, radius, borders, elevation, motion and breakpoints. Group colours into semantic roles
+(primary, accent, background, surface, text, muted, status colours). Keep raw source values as
+evidence, never as every component's editable prop.
+
+## What the brand kit is, and who writes it
+
+- `get_project` returns `brandKit`: colours (`primary`, `accent`, `background`, `surface`,
+  `text`, `muted`), `typography` (`headingFont`, `bodyFont`), `radius` (`sharp`/`rounded`/`pill`),
+  and optional `typeScale`, `spacing`, `elevation`, `motion` and gradients. A project that never
+  saved one still returns the default kit.
+- **Colours and typography are edited in the dashboard**; no MCP tool writes them. Prepare a
+  precise proposal and map the source CSS to it; never say you changed them.
+- **The logo mark and favicon** are written with `set_brand_assets`, by the id of a media asset
+  of this project (upload it first). A slot a person chose is refused unless you pass
+  `replace: true`; ask before passing it.
+- **Gradients** are written with `set_brand_graphics`: a kind, an optional angle and 2-8 stops
+  that name kit colour keys, never a hex or a CSS string.
+- Every brand write is a version a person can restore in the dashboard.
+- The hosted renderer emits the kit as `--bcms-*` and `--brand-*` CSS custom properties, which
+  reach hosted pages only. A self-hosted site owns its tokens: bind its own presentation
+  variables to the approved kit, and declare its presentation in `bcms-presentation.json` at the
+  root of the deployed artifact.
+- `update_project` `presentation` themes the platform's own renderer with the same closed knobs
+  as a release's `bcms-presentation.json`. It does not restyle a deployed build.
+
+## Section styles
+
+Section style props are closed tokens, not free CSS: space is `none|xs|sm|md|lg|xl`, colour is
+`none|white|black|muted|mutedBg|primary|accent`. Never put a hex value from the brand into block
+props: a token follows a brand change, a copied hex does not. Style inspector properties:
+`CM-27`. Expose a curated choice (for example
+`Surface: Light / Dark / Brand`); never ask an editor for a hex, a class name or a font path.
+Say whether a change is brand-wide or one instance, and test that a token change keeps contrast
+and layout intact in every variant. Offer only controls the renderer actually applies; a missing
+style binding is a code or platform task, not a dashboard promise.
+
+## Typography and fonts
+
+Inventory family stacks, weights, styles, variable axes, local files, remote providers and
+where each is used. Match heading and body roles to the rendered code; do not swap a display
+face for the body face because it appears less often. Keep fallbacks and the loading strategy.
+Self-host a font file only when its licence allows it; otherwise keep the provider reference and
+list the dependency. Record licence evidence or "licence unknown".
+
+Keep semantic HTML apart from visual size: an H2 may use a display token without becoming an
+H1. Expose typography variants only where the design allows a real choice.
+
+## Logos, images, icons and video
+
+- **Logo kit.** Roles: primary, reverse, dark, compact mark, wordmark, favicon, where the source
+  proves them; mark the rest unclassified. Keep vector originals and transparency. The navigation
+  logo is a stored image on the layout; replace it there ([components.md](components.md) §4),
+  not in each page.
+- **Images.** A stored image value is an object (`url`, `altText`, asset id), never a bare
+  string; read it as one. Alt text, decorative state and caption belong to the usage. Keep
+  `srcset`/`sizes`, poster, lazy/preload intent and art direction. Decorative images render an
+  empty `alt`; informative ones need text that fits the context.
+- **Request the size you render.** Mint resize URLs with `@bettercms-ai/image-url`
+  (`urlFor = imageUrlBuilder({ baseUrl: mediaUrl })`, then `urlFor(asset).size(800, 450).url()`;
+  also `width`, `format`, `quality`, `fit`, `dpr` 1–3) and a
+  `srcset` of the widths the layout actually uses. Why: the original upload is often several
+  thousand pixels wide, and an unresized `url` ships all of it.
+- **Framing lives on the value, never in the model.** An asset carries one focal point (0–1
+  fractions), set with `update_media` `focalX`/`focalY` (null resets to the centre) or in the
+  dashboard; a URL with both dimensions and `fit` cover crops around it automatically. One
+  PLACEMENT can differ: the image value itself may carry `focal: { x, y }` and
+  `crop: { top, right, bottom, left }` (0–1, cut from each edge; the crop must leave a visible
+  window). The value's focal wins over the asset's; absent keys fall back to the asset. Draw a
+  value with `imageValueUrl(value, { w, h })` and `imageValueObjectPosition(value)` from
+  `@bettercms-ai/image-url`, never `.url` alone, or the crop is lost. The dashboard's asset Crop
+  rewrites the stored bytes for every usage. Never add focal or crop FIELDS to a model: they
+  belong on the image value.
+- **Image block width.** An image block's `props.width` is pixels, and every lane caps it at
+  the column (`max-width:100%`, height auto). Leave it unset to fill the column.
+- **Rich-text images.** A `builtin:image` block takes `align` (`full` | `center` | `left` |
+  `right`) and `size` (`small` | `medium` | `large` | `full`) in its fields. Both render on every
+  lane, with inline widths, so no site CSS is needed.
+- **Image facts ride on the delivered value.** Delivery adds `width`, `height`, `thumbHash` (a
+  ThumbHash placeholder) and `focalX`/`focalY` to each image value, read at request time and
+  omitted while unknown (object values only: a bare URL string stays a string). Reserve the box from `width`/`height`, decode `thumbHash` for a blur-up,
+  and fall back to a tiny variant (`width(24)`) when it is absent.
+- **Generate or edit an image.** `generate_image` { prompt, width?, height?, altText } adds an AI
+  image to the Media Library; `transform_image` { mediaId, prompt } saves an edited copy as a NEW
+  asset and keeps the original. Each costs 5 AI credits (free with the workspace's own Together
+  key). Always set `altText`, and use them only where the user wants generated imagery: never to
+  stand in for a real product, person or place.
+- **SVG.** Every SVG upload is sanitised on the way in, and SVGs are served as vectors (no
+  raster variants). Keep safe icons as SVG and expose icon choice, size and colour token.
+  Functional icons need an accessible label or adjacent text. Editing SVG paths is not a CMS
+  feature; the text inside an SVG is not a bindable field ([bindings.md](bindings.md) §2).
+- **Video.** Inventory format, host, poster, captions, autoplay/mute/loop and cost. Do not copy
+  every video into the media library by default; keep a streaming provider reference where the
+  site depends on one.
+
+## Media host
+
+Use `mediaBaseUrl` from `get_project`: media is served from the CDN origin or the API origin of
+the backend that owns the asset ids. `set_media_delivery` is the owner's decision, asked every
+time. If a stored URL 404s, find the owning asset and report it; never re-save content to "move"
+assets. How templates and resize URLs use it: [frameworks.md](frameworks.md) Media host.
+
+## Presentation-mode UX
+
+Show only meaningful controls, and state the scope before a change:
+
+```text
+Brand                    [sitewide, reviewed]
+  Logos · Colors · Typography · Spacing / Radius / Motion
+
+Selected hero image      [this instance]
+  Asset · Alt text / Decorative · Caption
+```
+
+Keep provenance and licence status visible to developers, away from everyday editing.
+
+## Acceptance
+
+- Every local asset resolves from the project's media store; external dependencies are listed.
+- Logo roles and fonts carry evidence and licence status.
+- Colour, type and spacing changes go through tokens and keep contrast and responsive layout.
+- Editing a usage's alt text or caption changes the right rendered image.
+- Icons work in every intended theme and state.
+- Baseline and changed screenshots are compared; material differences are explained.

package/dist/skills/bettercms/references/next.md

@@ -0,0 +1,93 @@
+---
+title: "Next.js adapter"
+description: "The @bettercms-ai/next client, draft and revalidation routes, rendering exports, pagination and 404 handling, and static export with the snapshot."
+---
+
+# @bettercms-ai/next
+
+Read this when the repo has `next.config.*`. Shared rules (hosting modes, env map, tags, value
+shapes) are in [frameworks.md](frameworks.md).
+
+## Client
+
+`createBetterCMS<Schema>(config)` from `@bettercms-ai/next`, typed by the file
+`bettercms-codegen` writes. Config: `workspace` (slug), `apiKey` (delivery key), `revalidate`
+(ISR seconds, or `false`). Keep the key server-side: `BETTERCMS_API_KEY`, never
+`NEXT_PUBLIC_*`.
+
+## Draft preview (App Router, mounted by you)
+
+Nothing is mounted automatically. Add the routes:
+
+- `createDraftModeRoute({ apiUrl })` → export `GET` from the route your project's preview link
+  points at. It reads `?token=&redirect=`, has the backend validate the token, enables Next draft
+  mode, stores the token in the httpOnly `bcms-preview-token` cookie and redirects.
+- `createDisableDraftRoute()` → export `GET` from an exit route.
+- Read drafts with `getEntry(slug, { preview: true, previewToken })`. `preview: true` without a
+  token throws.
+
+## Revalidation route
+
+`createRevalidateRoute({ secret })` → export `POST`. With `secret` set it verifies
+`X-BetterCMS-Signature` against the raw body, then calls `revalidateTag` for each tag in the
+webhook. Use the project's webhook secret from the dashboard (the package docs name the env
+`BCMS_REVALIDATE_SECRET`; any server env works). Tag your reads with the backend's tag strings
+([frameworks.md](frameworks.md) Revalidation).
+
+## Rendering
+
+| Export | Use |
+|---|---|
+| `BcmsBlocks` | Render a block tree; pass `components` from `readComponents()` |
+| `readComponents()` | Component definitions from `bcms-content.json` |
+| `BcmsField` | `path`, `kind` (`richtext`/`image`), `as`; server-safe |
+| `bind`, `bindProps` | Binding attributes; instance-aware inside components |
+| `BcmsForm` + `getForm(idOrName)` | Forms from the snapshot ([forms-and-interactions.md](forms-and-interactions.md)) |
+| `buildMetadata(page, siteDefaults, location?)` | Next `Metadata` from native SEO fields |
+| `llmsTxtRoute(config)` | An `llms.txt` route handler |
+| `imageUrlBuilder({ baseUrl })` | Resize URLs. No `BcmsImage` in Next; same media-host rules as Astro |
+
+Rules:
+
+- Binding attributes are always rendered; they are inert for visitors. Do not gate them behind
+  draft mode.
+- Pass `location` `{ siteUrl, path }` to `buildMetadata`. Without it the site URL comes from
+  `BETTERCMS_SITE_URL` and the path from the page slug; an app that serves pages under a prefix
+  (`/docs/[slug]`) must pass `location.path` or its canonical is wrong.
+- The package ships no sitemap or robots helper. Write `app/sitemap.ts` and `app/robots.ts`
+  yourself from published content, and leave out pages marked noindex.
+
+## Lists, pagination and missing content
+
+- `listEntries(model, { page, perPage })`: `page` is 1-based; `perPage` defaults to 20 and the
+  API caps it at 100. The result carries `items`, `totalItems`, `totalPages`, `hasNextPage` and
+  `hasPreviousPage`: drive the pager from those, never from `items.length`. Pass `select` on list
+  pages so each card fetches only the keys it renders.
+- A page route (`/blog/page/[n]`) answers `notFound()` when `n` is past `totalPages`; page 1 of an
+  empty collection is a 200 with an empty state, not a 404. Prerender pages 1…`totalPages` from
+  `generateStaticParams`.
+- `getEntry(slug)` returns `null` on a 404: call `notFound()` on `null`, never render an empty
+  shell with a 200. Why: an empty 200 is indexed as a thin page, and a typo'd slug never reads as
+  missing.
+- `listEntries` THROWS `BetterCMSError` on a 404 (an unknown workspace or model), on purpose: an
+  empty list there would hide a wrong model slug. Let it fail the build; do not catch it into `[]`.
+
+## Static export (`output: "export"`)
+
+- Run `bettercms-snapshot` before `next build`, every build (make it the prebuild step). It writes
+  `bcms-content.json` from `BETTERCMS_API_URL`, `BETTERCMS_API_KEY`, `BETTERCMS_WORKSPACE`.
+- Without the snapshot the reads throw `SNAPSHOT_MISSING`. Why it throws instead of fetching:
+  a live fetch would turn pages into dynamic routes, and a static export silently leaves them out
+  of `out/`.
+- A preview build that must read live sets `BETTERCMS_PREVIEW=1`.
+- Draft mode and the revalidation route need a server; a static export has neither. Content
+  changes reach a static site only by rebuilding it.
+
+## Traps
+
+| Symptom | Cause | Rule |
+|---|---|---|
+| Empty `out/` after `next build` | No snapshot | Run `bettercms-snapshot` first |
+| Page never updates after publish | Read tags do not match backend tags | Use `bcms:{workspace}:…` tags |
+| Component instance renders nothing | `components` not passed | `readComponents()` into `BcmsBlocks` |
+| Canonical missing or wrong only on the self-hosted site | `buildMetadata` without `location`, and no `BETTERCMS_SITE_URL` or a prefixed route | Pass `{ siteUrl, path }` |

package/dist/skills/bettercms/references/other-frameworks.md

@@ -0,0 +1,66 @@
+---
+title: "Other frameworks"
+description: "Reading BetterCMS content from Nuxt, SvelteKit, React Router or Vite through the SDK createClient read core: options, 404 behaviour, env names, and what only the Astro and Next adapters provide."
+---
+
+# Other frameworks
+
+Read this when the repo has neither `astro.config.*` nor `next.config.*`. Only Astro and Next have
+adapters; everything else reads through the framework-agnostic core in `@bettercms-ai/sdk`, the
+same one both adapters wrap. Shared rules (hosting modes, value shapes, media host, revalidation
+tags) are in [frameworks.md](frameworks.md).
+
+## 1. The client
+
+```ts
+import { createClient } from "@bettercms-ai/sdk";
+
+export const bcms = createClient({
+  apiUrl: process.env.BCMS_API_URL!,     // the backend origin; the SDK adds /api/v1/delivery/<workspace>
+  workspace: process.env.BCMS_WORKSPACE!,
+  projectId: process.env.BCMS_PROJECT_ID, // scopes listForms
+});
+```
+
+Reading published content needs no key. The platform sets `BCMS_API_URL`, `BCMS_WORKSPACE` and
+`BCMS_PROJECT_ID` on every build and running server app, and again under each framework's public
+prefix (`NUXT_PUBLIC_`, `PUBLIC_`, `VITE_`…); the table is in
+[external-content.md](external-content.md). Never add them to `.env`.
+
+| Option | Use |
+|---|---|
+| `perspective: "drafts"` | Draft reads; needs a `content:read:draft` key or a `previewToken`. Stega is on by default there ([bindings.md](bindings.md) §5) |
+| `cache: true` | Collapse identical GETs for the client's life. Only for a static build (one point-in-time dataset); never in dev, SSR or drafts |
+| `timeout` | Per-attempt ms, default 10000 |
+
+## 2. Methods and their 404s
+
+| Method | Returns | On a missing slug |
+|---|---|---|
+| `getPage(slug)` | the page (`blocks`, meta columns) | `null`, after scanning the page list |
+| `getEntry(slug, { depth, select })` | one entry | throws `BetterCMSError` with `status` 404 |
+| `listEntries({ model, page, perPage, depth, select })` | `{ items, page, perPage, totalItems, totalPages, hasNextPage, hasPreviousPage }` | a list 404 (unknown model or workspace) throws |
+| `listPages`, `listComponents`, `getLayout`, `listForms` | pages, component definitions, the Global Layout (`null` if none), forms (render only `status: "published"`) | |
+
+Catch the 404 on `getEntry` and answer the framework's not-found (a 404 status, never an empty
+200). Let a list 404 fail the build. Drive pagers from `totalPages`/`hasNextPage`.
+
+## 3. Where to call it
+
+Call the client only in code that runs on the server or at build time, so a key (drafts) never
+reaches the bundle: a Nuxt server route or `useAsyncData` on the server, a SvelteKit
+`+page.server.ts` `load`, a React Router `loader`. A browser-only Vite SPA reads published content
+with the public-prefixed variables and no key.
+
+## 4. What only the adapters give you
+
+No `BcmsBlocks`/`BcmsField` components, no `bind`/`bindProps` helpers, no draft routes and no
+snapshot bin exist for these frameworks. So:
+
+- Render component blocks yourself from `listComponents()` definitions, and write binding
+  attributes by hand per [bindings.md](bindings.md) (`data-bcms-field`, `data-bcms-block`).
+- Rich text: read it through the SDK's `plain`, `rich` or `portableText` helpers, which accept a
+  bare string or the `{ format, value, html }` envelope.
+- Images: `imageUrlBuilder` is re-exported from the SDK ([media-and-brand.md](media-and-brand.md)).
+- Meta: `resolveSeo` merges page over site defaults; write the result into `<head>` yourself.
+- Verify with the two-path smoke test in [frameworks.md](frameworks.md) Verify.

package/dist/skills/bettercms/references/portable-text.md

@@ -0,0 +1,206 @@
+---
+title: "Field types and Portable Text"
+description: "Choosing field types, the Portable Text write contract and grammar, converting HTML or Markdown structurally, and serializing rich text."
+---
+
+# Field types and Portable Text
+
+**Outcome.** The editor shows the right control for each visible value, the page keeps its
+semantic HTML, a button or card title cannot turn into the wrong heading level, and every rich
+text value you write is stored and rendered as written. Binding grammar:
+[bindings.md](bindings.md); field and schema doctrine: `bettercms://playbook/schema`.
+
+## 1. Decide what the user is editing
+
+Inspect the rendered element, its source component, role, ancestors, repeated instances and
+responsive variants, and the existing schema. Keep four concerns apart; they must not collapse
+into one rich-text field:
+
+- **content** (the words),
+- **semantic tag** (H1, H2, p, button),
+- **presentation** (font, size, colour),
+- **behaviour** (href, modal trigger).
+
+Choose a field's type, label, validation and allowed rich-text features from its context on the
+page, not from a rule that every string is rich text. When one source value renders in two
+semantic contexts, split the display role from the content, or make the level a controlled
+component prop, never an open toolbar choice.
+
+## 2. Semantic field matrix
+
+The model's field types are `text`, `richtext`, `document` (the article body, at most one per
+collection), `image`, `boolean`, `number`, `select` and references, among others. The matrix is
+intended UX; confirm each control exists in the connected editor before promising it.
+
+| Rendered role | Field | Editor options | Render rule |
+|---|---|---|---|
+| Page or hero title | text, or one-block richtext | title role only; inline emphasis if the design needs it | one H1 per page; a title shown twice is not two H1s |
+| Section heading | text | no heading picker; level comes from the component | usually H2, H3 when nested |
+| Card or item title | text | no toolbar | H3/H4 by nesting; a reused card never adds an H1 |
+| Eyebrow, badge, button label, nav item, form label | text | plain | keep the real element (`span`, `a`, `button`, `label`) |
+| Summary | text; richtext only when inline links are needed | normal paragraphs, few marks | `p`; no heading or list controls |
+| Article body | `document` | the schema's allowed blocks | keep the whole outline and every supported node |
+| FAQ question | text | plain | inside an accessible trigger; the component owns the level |
+| FAQ answer, modal body | narrowed richtext | paragraphs, lists, links, emphasis | focus and ARIA live outside the value |
+| Image | image | asset, alt text, caption | bind `src` and `alt` separately |
+| Link or button | grouped fields | label, link, style variant | no raw HTML, no `javascript:` URL |
+
+"Disabled" controls mean the field's accept list removes irrelevant formatting; the field stays
+editable. Keep a source's unusual but valid hierarchy when changing it would alter meaning, and
+flag it for review. The page title is the page's `h1`; body rich text starts at `h2`. Group the
+side panel by what the editor sees (`Button → Label, Link, Style`;
+`Image → Asset, Alt text, Caption`) and show the instance scope.
+
+## 3. The write contract
+
+- Write a richtext value as a Portable Text array. An array passes straight through to storage.
+- Never write a bare string to a richtext field. On write a bare string is parsed as HTML or
+  Markdown (a conversion you did not review), while the reader treats a bare string as literal
+  text, so the same string means two different things depending on the path.
+- The stored value is an envelope `{ format: "portable-text-1", value, html }`. `value` is the
+  truth; `html` is a derived cache. Never write or patch `html`.
+- A per-paragraph address (`base#<_key>`) is an edit target, not a write path: write the whole
+  field ([bindings.md](bindings.md) §3).
+- The `/presence/pt-patch` endpoint relays live edits between people in the editor. It is not a
+  save. Persist through the content write tools.
+
+## 4. Portable Text rules
+
+Names come from `packages/richtext/src/schema.ts`. A field's `accept` list narrows them; use only
+names the field accepts.
+
+| Part | Allowed names | Granted by accept element |
+|---|---|---|
+| block `style` | `normal` always; `h1`…`h6`; `blockquote` | heading element; `p` |
+| decorators (span `marks`) | `strong`, `em`, `underline`, `strike-through`, `code`, `highlight` | `b`, `i`, `u`, `s`, `code`, `mark` |
+| annotations (`markDefs`) | `link` {href, target, className}; `styled` {tag, className, attrs} | `link`/`internalLink`; always |
+| `listItem` | `bullet`, `number`, `check` | `ul`, `ol`, `checklist` |
+| block objects | `bcmsDivider`; `bcmsCode` {code, language}; `bcmsBlock` {schemaKey, schemaLabel, fields}; `table` {rows} | `p`; `pre`; `image`/`embed`/`columns`; `table` |
+| inline objects | `bcmsMention` {label} | always |
+
+- **Keys**: every block, span, markDef, row and cell has `_key` matching `^[A-Za-z0-9-]{1,32}$`,
+  unique in the document. Keys are editor addresses, so keep existing ones.
+- **Marks**: a span's `marks` entry is a decorator name or the `_key` of a markDef in the same
+  block. Every markDef is referenced by at least one span.
+- **Lists are flat**: a list item is a normal block with `listItem` and `level` (1 = top). Never
+  nest blocks inside a list container. A `check` item carries `checked: true|false`.
+- **Tables**: a cell holds blocks in `content`, not a string. `header: true` marks a `<th>` cell;
+  `head: true` puts a row in `<thead>`.
+- **`styled`** carries a site's own inline markup; `tag` is one of `span`, `small`, `sup`, `sub`,
+  `kbd`, `abbr`, `time`, or a decorator tag (`strong`, `em`, `b`, `i`, `u`, `s`, `mark`, `code`, …)
+  that carries a class. A `link` keeps its class as `className`.
+- **Top-level `_type`** is one of `block`, `bcmsBlock`, `table`, `bcmsCode`, `bcmsDivider`,
+  `bcmsMention`. A name outside that list is refused on write, by name and `_key`, because the
+  block would disappear from the live site. The refusal is **top level only**: a foreign mark
+  passes and its text renders unmarked; a foreign inline child passes and renders nothing. Check
+  those yourself.
+
+A paragraph with a bold word and a link:
+
+<!-- pt-example -->
+```json
+[
+  {
+    "_type": "block",
+    "_key": "intro",
+    "style": "normal",
+    "markDefs": [{ "_type": "link", "_key": "lnk1", "href": "/pricing" }],
+    "children": [
+      { "_type": "span", "_key": "s1", "text": "See ", "marks": [] },
+      { "_type": "span", "_key": "s2", "text": "pricing", "marks": ["strong", "lnk1"] }
+    ]
+  }
+]
+```
+
+A flat two-level bullet list:
+
+<!-- pt-example -->
+```json
+[
+  { "_type": "block", "_key": "li1", "style": "normal", "listItem": "bullet", "level": 1, "markDefs": [],
+    "children": [{ "_type": "span", "_key": "li1s", "text": "Plans", "marks": [] }] },
+  { "_type": "block", "_key": "li2", "style": "normal", "listItem": "bullet", "level": 2, "markDefs": [],
+    "children": [{ "_type": "span", "_key": "li2s", "text": "Monthly", "marks": [] }] }
+]
+```
+
+A table with a header row:
+
+<!-- pt-example -->
+```json
+[
+  {
+    "_type": "table",
+    "_key": "tbl",
+    "rows": [
+      { "_key": "r1", "head": true, "cells": [
+        { "_key": "c1", "header": true, "content": [
+          { "_type": "block", "_key": "c1b", "style": "normal", "markDefs": [],
+            "children": [{ "_type": "span", "_key": "c1s", "text": "Plan", "marks": [] }] }
+        ] }
+      ] },
+      { "_key": "r2", "cells": [
+        { "_key": "c2", "content": [
+          { "_type": "block", "_key": "c2b", "style": "normal", "markDefs": [],
+            "children": [{ "_type": "span", "_key": "c2s", "text": "Pro", "marks": [] }] }
+        ] }
+      ] }
+    ]
+  }
+]
+```
+
+Site markup kept through `styled`:
+
+<!-- pt-example -->
+```json
+[
+  {
+    "_type": "block",
+    "_key": "price",
+    "style": "h2",
+    "markDefs": [{ "_type": "styled", "_key": "sm1", "tag": "small", "className": "muted" }],
+    "children": [
+      { "_type": "span", "_key": "p1", "text": "$29 ", "marks": [] },
+      { "_type": "span", "_key": "p2", "text": "per month", "marks": ["sm1"] }
+    ]
+  }
+]
+```
+
+## 5. Converting into Portable Text
+
+1. Parse HTML, Markdown, MDX or source-CMS blocks structurally; never flatten markup with regex.
+2. Map headings, paragraphs, lists, links, marks, tables, images and embedded components to
+   supported nodes. Resolve internal links to page or entry references where possible.
+3. Sanitise HTML and URLs. Keep the source path and write a loss report for every unsupported
+   node, embed or script. A foreign custom block needs a renderer and a mapping, or a visible
+   conversion warning.
+4. Generate deterministic keys on the first import; preserve them on later edits and re-imports.
+5. Compare text, link count and targets, heading outline, list levels and media references
+   between source and result.
+
+## 6. Serializing out of Portable Text
+
+1. Render every allowed style, list type, decorator, annotation, inline object and custom block
+   explicitly. Report unknown nodes; never drop them silently.
+2. Use a context-aware renderer for internal links, images and embeds, and keep their
+   accessibility labels.
+3. Build plain-text and SEO excerpts from the semantic text, with preview markers stripped
+   (`stripStega`) and no HTML or hidden JSON.
+4. Markdown export loses interactive custom blocks; emit typed references or a loss report, and
+   never claim a lossless round trip.
+
+The public Portable Text specification describes the general block model. BetterCMS's own schema
+and accept list decide the subset; do not paste Sanity-only types or serializers.
+
+## Acceptance
+
+- Page title, section title, card title, button label, summary and article body each open the
+  expected controls; a reused card on a second page adds no H1.
+- Rich text keeps links, nested marks, lists, tables, custom blocks and stable keys; unknown
+  nodes are logged, and nothing disappears silently.
+- Changing a label, a URL or a style changes only that property on that instance.
+- Long, empty and translated text render acceptably.
+- After writing rich text, `get_binding_report` for the route is clean.